developer-ai 1.0.0

package/skills/error-handling/SKILL.md

@@ -0,0 +1,504 @@
+---
+name: error-handling
+description: Guide for implementing robust error handling. Use when designing error handling strategies, creating custom errors, implementing retry logic, or improving error messages. Covers error types, try-catch patterns, async error handling, and user-facing errors.
+---
+
+# Error Handling Skill
+
+This skill provides guidance for implementing robust, user-friendly error handling in applications.
+
+## Overview
+
+Good error handling improves debugging, user experience, and system reliability. This skill covers patterns for catching, processing, and communicating errors effectively.
+
+## Error Hierarchy
+
+### Custom Error Classes
+
+```javascript
+// Base application error
+class AppError extends Error {
+  constructor(message, statusCode = 500, code = 'INTERNAL_ERROR') {
+    super(message);
+    this.name = this.constructor.name;
+    this.statusCode = statusCode;
+    this.code = code;
+    this.isOperational = true;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+// Specific error types
+class ValidationError extends AppError {
+  constructor(message, details = []) {
+    super(message, 400, 'VALIDATION_ERROR');
+    this.details = details;
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(resource = 'Resource') {
+    super(`${resource} not found`, 404, 'NOT_FOUND');
+  }
+}
+
+class UnauthorizedError extends AppError {
+  constructor(message = 'Authentication required') {
+    super(message, 401, 'UNAUTHORIZED');
+  }
+}
+
+class ForbiddenError extends AppError {
+  constructor(message = 'Access denied') {
+    super(message, 403, 'FORBIDDEN');
+  }
+}
+
+class ConflictError extends AppError {
+  constructor(message = 'Resource conflict') {
+    super(message, 409, 'CONFLICT');
+  }
+}
+```
+
+### Usage
+
+```javascript
+function getUser(id) {
+  const user = users.find(u => u.id === id);
+  if (!user) {
+    throw new NotFoundError('User');
+  }
+  return user;
+}
+
+function validateEmail(email) {
+  if (!email.includes('@')) {
+    throw new ValidationError('Invalid email format', [
+      { field: 'email', message: 'Must contain @' }
+    ]);
+  }
+}
+```
+
+## Try-Catch Patterns
+
+### Basic Try-Catch
+
+```javascript
+try {
+  const result = riskyOperation();
+  return result;
+} catch (error) {
+  // Handle specific errors differently
+  if (error instanceof ValidationError) {
+    return { error: error.details };
+  }
+  if (error instanceof NotFoundError) {
+    return { error: 'Item not found' };
+  }
+  // Re-throw unexpected errors
+  throw error;
+}
+```
+
+### With Finally
+
+```javascript
+let connection;
+try {
+  connection = await database.connect();
+  const result = await connection.query(sql);
+  return result;
+} catch (error) {
+  logger.error('Database query failed', { error, sql });
+  throw new AppError('Database operation failed');
+} finally {
+  // Always cleanup
+  if (connection) {
+    await connection.release();
+  }
+}
+```
+
+### Wrapping Errors
+
+```javascript
+async function fetchUserData(userId) {
+  try {
+    const response = await fetch(`/api/users/${userId}`);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    return await response.json();
+  } catch (error) {
+    // Wrap with context
+    throw new AppError(
+      `Failed to fetch user ${userId}: ${error.message}`,
+      500,
+      'FETCH_ERROR'
+    );
+  }
+}
+```
+
+## Async Error Handling
+
+### Async/Await
+
+```javascript
+// With try-catch
+async function processOrder(orderId) {
+  try {
+    const order = await getOrder(orderId);
+    const payment = await processPayment(order);
+    await updateInventory(order.items);
+    await sendConfirmation(order);
+    return { success: true, payment };
+  } catch (error) {
+    logger.error('Order processing failed', { orderId, error });
+    throw error;
+  }
+}
+
+// Express async wrapper
+const asyncHandler = (fn) => (req, res, next) => {
+  Promise.resolve(fn(req, res, next)).catch(next);
+};
+
+app.get('/orders/:id', asyncHandler(async (req, res) => {
+  const order = await getOrder(req.params.id);
+  res.json(order);
+}));
+```
+
+### Promise Error Handling
+
+```javascript
+// Chain with catch
+fetchData()
+  .then(processData)
+  .then(saveResult)
+  .catch(handleError);
+
+// Multiple promises
+const results = await Promise.allSettled([
+  fetchUsers(),
+  fetchOrders(),
+  fetchProducts(),
+]);
+
+const errors = results
+  .filter(r => r.status === 'rejected')
+  .map(r => r.reason);
+
+if (errors.length) {
+  logger.warn('Some operations failed', { errors });
+}
+```
+
+### Timeout Handling
+
+```javascript
+function withTimeout(promise, ms) {
+  const timeout = new Promise((_, reject) => {
+    setTimeout(() => reject(new Error('Operation timed out')), ms);
+  });
+  return Promise.race([promise, timeout]);
+}
+
+try {
+  const result = await withTimeout(fetchData(), 5000);
+} catch (error) {
+  if (error.message === 'Operation timed out') {
+    // Handle timeout specifically
+  }
+  throw error;
+}
+```
+
+## Express Error Handling
+
+### Error Middleware
+
+```javascript
+// Error handler middleware (must have 4 parameters)
+function errorHandler(err, req, res, next) {
+  // Log error
+  logger.error({
+    message: err.message,
+    stack: err.stack,
+    path: req.path,
+    method: req.method,
+    body: req.body,
+  });
+  
+  // Operational errors - safe to send to client
+  if (err.isOperational) {
+    return res.status(err.statusCode).json({
+      error: {
+        code: err.code,
+        message: err.message,
+        ...(err.details && { details: err.details }),
+      },
+    });
+  }
+  
+  // Programming errors - don't leak details
+  res.status(500).json({
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'Something went wrong',
+    },
+  });
+}
+
+// 404 handler
+function notFoundHandler(req, res) {
+  res.status(404).json({
+    error: {
+      code: 'NOT_FOUND',
+      message: `Route ${req.method} ${req.path} not found`,
+    },
+  });
+}
+
+// Apply middleware
+app.use(notFoundHandler);
+app.use(errorHandler);
+```
+
+### Validation Error Handling
+
+```javascript
+const { validationResult } = require('express-validator');
+
+function handleValidationErrors(req, res, next) {
+  const errors = validationResult(req);
+  
+  if (!errors.isEmpty()) {
+    throw new ValidationError('Validation failed', 
+      errors.array().map(e => ({
+        field: e.path,
+        message: e.msg,
+      }))
+    );
+  }
+  
+  next();
+}
+```
+
+## React Error Handling
+
+### Error Boundaries
+
+```jsx
+class ErrorBoundary extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error, errorInfo) {
+    // Log to error reporting service
+    logErrorToService(error, errorInfo);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback || <ErrorFallback error={this.state.error} />;
+    }
+
+    return this.props.children;
+  }
+}
+
+// Usage
+<ErrorBoundary fallback={<div>Something went wrong</div>}>
+  <MyComponent />
+</ErrorBoundary>
+```
+
+### Async Error Handling in React
+
+```jsx
+function useAsync(asyncFn, dependencies = []) {
+  const [state, setState] = useState({
+    data: null,
+    error: null,
+    loading: true,
+  });
+
+  useEffect(() => {
+    setState(s => ({ ...s, loading: true }));
+    
+    asyncFn()
+      .then(data => setState({ data, error: null, loading: false }))
+      .catch(error => setState({ data: null, error, loading: false }));
+  }, dependencies);
+
+  return state;
+}
+
+// Usage
+function UserProfile({ userId }) {
+  const { data: user, error, loading } = useAsync(
+    () => fetchUser(userId),
+    [userId]
+  );
+
+  if (loading) return <Loading />;
+  if (error) return <ErrorMessage error={error} />;
+  return <Profile user={user} />;
+}
+```
+
+## Retry Logic
+
+### Exponential Backoff
+
+```javascript
+async function withRetry(fn, options = {}) {
+  const {
+    maxAttempts = 3,
+    baseDelay = 1000,
+    maxDelay = 10000,
+    shouldRetry = () => true,
+  } = options;
+
+  let lastError;
+  
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      
+      if (attempt === maxAttempts || !shouldRetry(error)) {
+        throw error;
+      }
+      
+      const delay = Math.min(
+        baseDelay * Math.pow(2, attempt - 1),
+        maxDelay
+      );
+      
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  
+  throw lastError;
+}
+
+// Usage
+const data = await withRetry(
+  () => fetchFromAPI('/data'),
+  { 
+    maxAttempts: 3,
+    shouldRetry: (error) => error.status >= 500,
+  }
+);
+```
+
+## Error Messages
+
+### User-Facing Messages
+
+```javascript
+const UserMessages = {
+  VALIDATION_ERROR: 'Please check your input and try again.',
+  NOT_FOUND: 'The requested item could not be found.',
+  UNAUTHORIZED: 'Please log in to continue.',
+  FORBIDDEN: 'You don\'t have permission to do this.',
+  CONFLICT: 'This item already exists.',
+  NETWORK_ERROR: 'Unable to connect. Please check your internet.',
+  INTERNAL_ERROR: 'Something went wrong. Please try again later.',
+};
+
+function getUserMessage(error) {
+  return UserMessages[error.code] || UserMessages.INTERNAL_ERROR;
+}
+```
+
+### Developer-Facing Messages
+
+```javascript
+// Include context for debugging
+throw new AppError(
+  `Failed to process order ${orderId}: Payment declined for user ${userId}`,
+  400,
+  'PAYMENT_DECLINED'
+);
+
+// Structured logging
+logger.error('Order processing failed', {
+  orderId,
+  userId,
+  amount,
+  paymentMethod,
+  error: error.message,
+  stack: error.stack,
+});
+```
+
+## Error Logging
+
+### Structured Logging
+
+```javascript
+const winston = require('winston');
+
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.json()
+  ),
+  defaultMeta: { service: 'api' },
+  transports: [
+    new winston.transports.File({ filename: 'error.log', level: 'error' }),
+    new winston.transports.File({ filename: 'combined.log' }),
+  ],
+});
+
+// Log with context
+function logError(error, context = {}) {
+  logger.error({
+    message: error.message,
+    code: error.code,
+    stack: error.stack,
+    ...context,
+  });
+}
+```
+
+## Error Handling Checklist
+
+### Implementation
+- [ ] Custom error classes created
+- [ ] Error middleware configured
+- [ ] Async errors handled
+- [ ] Error boundaries in React
+
+### Logging
+- [ ] Errors logged with context
+- [ ] Stack traces captured
+- [ ] No sensitive data in logs
+- [ ] Log levels appropriate
+
+### User Experience
+- [ ] User-friendly error messages
+- [ ] Actionable feedback provided
+- [ ] Recovery options available
+- [ ] Loading/error states handled
+
+### Monitoring
+- [ ] Error tracking configured
+- [ ] Alerts for critical errors
+- [ ] Error trends monitored
+- [ ] Resolution time tracked