// ✅ Good: Descriptive and specific
createError({ type: 'EmailValidationError', message: '...' });
createError({ type: 'DatabaseConnectionTimeout', message: '...' });
createError({ type: 'InsufficientInventoryError', message: '...' });

// ❌ Bad: Generic and unclear
createError({ type: 'Error', message: '...' });
createError({ type: 'ValidationError', message: '...' }); // Too generic
createError({ type: 'Err', message: '...' }); // Abbreviated

// ✅ Good: Includes actionable debugging information
createError({
  type: 'ApiValidationError',
  message: 'Request validation failed',
  context: {
    endpoint: '/api/users',
    method: 'POST',
    validationErrors: {
      email: 'Invalid format',
      age: 'Must be between 18 and 120'
    },
    requestId: 'req_123456'
  }
});

// ❌ Bad: No context for debugging
createError({
  type: 'ValidationError',
  message: 'Validation failed'
});

// ✅ Create reusable factories for your domain
class UserErrorFactory {
  static notFound(userId: string) {
    return createError({
      type: 'UserNotFoundError' as const,
      message: `User with ID ${userId} not found`,
      context: { userId, entity: 'User' }
    });
  }

  static alreadyExists(email: string) {
    return createError({
      type: 'UserAlreadyExistsError' as const,
      message: `User with email ${email} already exists`,
      context: { email, entity: 'User' }
    });
  }

  static invalidCredentials() {
    return createError({
      type: 'InvalidCredentialsError' as const,
      message: 'Invalid email or password',
      context: { entity: 'User', action: 'authenticate' }
    });
  }
}

// Usage
const user = await tryAsync(() => findUser(userId));
if (!user) {
  return UserErrorFactory.notFound(userId);
}

// ✅ Use const assertions for literal types
function createApiError(status: number, message: string) {
  const type = status >= 500 
    ? 'ServerError' as const
    : status >= 400 
    ? 'ClientError' as const
    : 'ApiError' as const;
    
  return createError({
    type,
    message,
    context: { status, category: status >= 500 ? 'server' : 'client' }
  });
}

// ✅ Use union types for predefined error categories
type ValidationErrorType = 
  | 'RequiredFieldError'
  | 'FormatValidationError' 
  | 'RangeValidationError'
  | 'CustomValidationError';

function createValidationError(
  type: ValidationErrorType,
  field: string,
  message: string
) {
  return createError({
    type,
    message: `${type}: ${message}`,
    context: { field, type, message }
  });
}

// Usage
const apiError = createApiError(404, 'Resource not found');
const validationError = createValidationError('email', 'Invalid format', 'The email is not valid');

// Define your expected context structure
interface ValidationContext {
  field: string;
  value: unknown;
  rule: string;
}

// Create a type guard
function isValidationContext(context: unknown): context is ValidationContext {
  return typeof context === 'object' && 
         context !== null && 
         'field' in context &&
         'rule' in context &&
         typeof (context as any).field === 'string';
}

// Safe usage
const result = trySync(() => validateEmail(email));
if (isTryError(result) && isValidationContext(result.context)) {
  // ✅ Now context is properly typed
  console.log(`Field ${result.context.field} failed rule: ${result.context.rule}`);
}

// Quick check with optional properties
function handleValidationError(error: TryError) {
  const context = error.context as { field?: string; rule?: string } | undefined;
  
  if (context?.field && context?.rule) {
    return `Validation failed for ${context.field}: ${context.rule}`;
  }
  
  return `Validation failed: ${error.message}`;
}

// Reusable helper for safe context access
function getContextValue<T>(
  error: TryError, 
  key: string, 
  defaultValue: T
): T {
  if (typeof error.context === 'object' && 
      error.context !== null && 
      key in error.context) {
    return (error.context as any)[key] ?? defaultValue;
  }
  return defaultValue;
}

// Usage
const field = getContextValue(error, 'field', 'unknown');
const status = getContextValue(error, 'status', 500);

// Define context interfaces for your domain
export interface ApiErrorContext {
  endpoint: string;
  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
  status?: number;
  requestId?: string;
}

export interface ValidationErrorContext {
  field: string;
  value: unknown;
  rule: string;
  constraints?: Record<string, unknown>;
}

export interface BusinessErrorContext {
  entity: string;
  operation: string;
  businessRule: string;
  metadata?: Record<string, unknown>;
}

// Create factory functions with typed context
export function createApiError(
  message: string, 
  context: ApiErrorContext
): TryError<'ApiError'> {
  return createError({
    type: 'ApiError' as const,
    message,
    context
  });
}

// Type guards for each context type
export function isApiErrorContext(context: unknown): context is ApiErrorContext {
  return typeof context === 'object' && 
         context !== null && 
         'endpoint' in context &&
         'method' in context;
}

// Usage
const error = createApiError('Failed to fetch user', {
  endpoint: '/api/users/123',
  method: 'GET',
  status: 404,
  requestId: 'req_abc123'
});

if (isTryError(error) && isApiErrorContext(error.context)) {
  // ✅ Fully typed access to context
  console.log(`${error.context.method} ${error.context.endpoint} failed`);
}