aidd-error-causes

Error Causes Rule

Use the error-causes library for all error handling in JavaScript/TypeScript code to enable structured error handling with named causes.

Why Error Causes?

• Enables structured error handling with named causes instead of relying on instanceof checks
• Works across memory realms (e.g., iframes) unlike instanceof
• Provides consistent error metadata (name, code, message, cause)
• Makes error handling explicit and self-documenting
• Allows for automatic error routing based on error names

Import Statement

import { createError } from "error-causes";

Basic Usage

Instead of throwing plain errors:

// ❌ DON'T
throw new Error('Config key "API_KEY" is required');

Use createError with structured metadata:

// ✅ DO
throw createError({
  name: 'ConfigurationError',
  message: 'Required configuration key "API_KEY" is not defined',
  code: 'MISSING_CONFIG_KEY',
  requestedKey: 'API_KEY'
});

Error Properties

Always include these properties in createError:

• name - Error name for matching (e.g., 'ValidationError', 'AuthenticationError')
• message - Human-readable error message
• code (optional) - Error code for programmatic handling
• Custom properties (optional) - Any additional context relevant to the error

Wrapping Caught Errors

When catching and re-throwing errors, preserve the original error as cause:

try {
  await someOperation();
} catch (originalError) {
  throw createError({
    name: 'OperationError',
    message: 'Failed to perform operation',
    code: 'OPERATION_FAILED',
    cause: originalError  // Preserve original error
  });
}

Factory Validation Errors

For factory functions that validate parameters at creation time:

const createMiddleware = ({ requiredParam } = {}) => {
  if (!requiredParam) {
    throw createError({
      name: 'ValidationError',
      message: 'requiredParam is required',
      code: 'MISSING_REQUIRED_PARAM'
    });
  }

  return async ({ request, response }) => {
    // middleware implementation
  };
};