@thalorlabs/errors/DOCSTYLE.md

Enhanced exception handling system for TypeScript applications with comprehensive error classes and debugging capabilities

# DOCSTYLE.md — @thalorlabs/errors

📄 JSDoc Standards for Error Classes

This document defines the standards for documenting error classes in @thalorlabs/errors. The goal is to make error handling easy to understand, maintain, and use across projects while keeping the docs concise and informative.

## 1. General Rules

- **Keep it clear**: error classes should have descriptive, concise docs.
- **Include**:
  - Description (what the error represents and when to use it)
  - `@example` with common usage patterns
  - HTTP status code and error context
- **Exclude**:
  - Owners, version numbers, dates → track via git and package.json
  - Use `@remarks` sparingly, only for non-obvious behavior or constraints.

### Error Class Policy

**This package only contains ThalorLabs error classes** - standardized error handling for our applications.

- ✅ Document: `ValidationError`, `DatabaseError`, `RateLimitError` (our error contracts)
- ❌ Never document: Third-party library error types, framework-specific errors
- Keep application-specific error logic local to the service that uses it

## 2. Template

```typescript
/**
 * Brief description of what the error represents and when to use it.
 *
 * Additional details about HTTP status code, error context, and usage scenarios.
 *
 * @example
 * throw new ValidationError('Invalid input data', [
 *   { field: 'email', message: 'Invalid email format' }
 * ], 'req-123');
 *
 * throw new DatabaseError('Connection failed', 'MongoDB', 'find',
 *   DatabaseErrorType.CONNECTION_FAILED, originalError, 'req-123');
 */
export class ErrorClassName extends CustomError {
  constructor(message: string, context?: any, requestId?: string) {
    super(statusCode, message, requestId, context);
  }
}
```

## 3. Examples

### ValidationError Class

```typescript
/**
 * Error for input validation failures with detailed field-level information.
 *
 * Used when request data fails validation with specific field errors.
 * Provides structured error information for API responses.
 *
 * @example
 * throw new ValidationError('Validation failed', [
 *   { field: 'email', message: 'Invalid email format', value: 'invalid-email' },
 *   { field: 'password', message: 'Password too short', value: '123' }
 * ], 'req-123');
 *
 * // Add more validation errors dynamically
 * validationError.addValidationError('age', 'Must be 18 or older', 16);
 */
export class ValidationError extends CustomError {
  validationErrors: ValidationErrorDetail[];

  constructor(
    message: string,
    validationErrors: ValidationErrorDetail[],
    requestId?: string,
    context?: Record<string, any>
  ) {
    super(422, message, requestId, context);
    this.validationErrors = validationErrors;
  }
}
```

### DatabaseError Class

```typescript
/**
 * Error for database operation failures with detailed context.
 *
 * Used when database operations fail with specific error types and context.
 * Includes database type, operation, and error classification.
 *
 * @example
 * throw new DatabaseError(
 *   'Connection timeout',
 *   'MongoDB',
 *   'find',
 *   DatabaseErrorType.CONNECTION_FAILED,
 *   originalError,
 *   'req-123',
 *   { collection: 'users', query: { _id: '123' } }
 * );
 */
export class DatabaseError extends CustomError {
  databaseType: string;
  operation: string;
  errorType: DatabaseErrorType;
  originalError?: Error;

  constructor(
    message: string,
    databaseType: string,
    operation: string,
    errorType: DatabaseErrorType,
    originalError?: Error,
    requestId?: string,
    context?: Record<string, any>
  ) {
    super(500, message, requestId, context);
    this.databaseType = databaseType;
    this.operation = operation;
    this.errorType = errorType;
    this.originalError = originalError;
  }
}
```

### DatabaseErrorType Enum

```typescript
/**
 * Enum for database error types.
 *
 * Used to classify different types of database failures for better error handling.
 */
export enum DatabaseErrorType {
  CONNECTION_FAILED = 'CONNECTION_FAILED',
  QUERY_FAILED = 'QUERY_FAILED',
  TRANSACTION_FAILED = 'TRANSACTION_FAILED',
  CONSTRAINT_VIOLATION = 'CONSTRAINT_VIOLATION',
  TIMEOUT = 'TIMEOUT',
  DEADLOCK = 'DEADLOCK',
  UNKNOWN = 'UNKNOWN',
}
```

## 4. Documentation Standards

### Error Class Documentation

- **Description**: What the error represents and when to use it
- **HTTP status**: Document the HTTP status code and meaning
- **Usage notes**: Any important context or error handling requirements
- **Examples**: 2-3 examples showing common usage patterns
- **Error context**: Document any special error context or properties

### Constructor Documentation

- **Parameters**: Document all constructor parameters
- **Optional parameters**: Note which parameters are optional and their defaults
- **Error context**: Explain any special error context or properties
- **Request tracking**: Document requestId and context usage

### Enum Documentation

- **Purpose**: What the enum represents
- **Values**: Brief description of each value
- **Usage**: How the enum is typically used in error handling

## 5. Examples Guidelines

- **Normal usage**: Show typical error throwing patterns
- **Error context**: Demonstrate context and request tracking
- **Error handling**: Show how errors are caught and handled
- **Integration**: Show how errors work with middleware and APIs

## 6. Notes

- Examples are mandatory for all error classes and enums
- Show both error creation and error handling patterns
- Include error context examples where relevant
- Use consistent formatting and spacing
- Reference related error classes and enums in examples