aidd-error-causes

name	aidd-error-causes
description	Use the error-causes library for structured error handling in JavaScript/TypeScript. Use when throwing errors, catching errors, defining error types, or implementing error routing.

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
  };
};

Testing Error Causes

In tests, verify the error's cause property:

let error;
try {
  functionThatThrows();
} catch (e) {
  error = e;
}

assert({
  given: 'invalid input',
  should: 'throw Error with cause',
  actual: error instanceof Error && error.cause !== undefined,
  expected: true
});

assert({
  given: 'invalid input',
  should: 'have correct error name',
  actual: error.cause.name,
  expected: 'ValidationError'
});

assert({
  given: 'invalid input',
  should: 'have correct error code',
  actual: error.cause.code,
  expected: 'MISSING_REQUIRED_PARAM'
});

Error Handler Pattern

For APIs that define multiple error types, use the errorCauses pattern:

import { errorCauses, createError } from "error-causes";

// Define all possible errors for your API
const [apiErrors, handleApiErrors] = errorCauses({
  NotFound: {
    code: 404,
    message: 'Resource not found'
  },
  ValidationError: {
    code: 400,
    message: 'Invalid input'
  },
  Unauthorized: {
    code: 401,
    message: 'Authentication required'
  }
});

const { NotFound, ValidationError, Unauthorized } = apiErrors;

// Throw errors
if (!resource) throw createError(NotFound);

// Handle errors with automatic routing
someAsyncCall()
  .catch(handleApiErrors({
    NotFound: ({ message }) => console.log(message),
    ValidationError: ({ message }) => console.log(message),
    Unauthorized: ({ message }) => redirect('/login')
  }));

Rules

1. Always use createError instead of new Error() for thrown errors
2. Always include name and message in error metadata
3. Include code when the error needs programmatic handling
4. Preserve original errors using the cause property when re-throwing
5. Add context with custom properties relevant to the error
6. Test the cause property in error tests, not just the error message
7. Define error types using errorCauses() for APIs with multiple error types