@jmruthers/pace-core 0.6.6 → 0.6.8

package/docs/standards/10-error-handling-patterns.md

@@ -1,401 +0,0 @@
-# Error Handling Patterns
-
-**🤖 Cursor Rule**: See [10-error-handling-patterns.mdc](../../cursor-rules/10-error-handling-patterns.mdc) for AI-optimized directives that automatically enforce error handling patterns.
-
-## Purpose
-
-This standard defines consistent error handling patterns across pace-core and consuming apps to ensure:
-- **User-friendly error messages** that don't expose internal details
-- **Type-safe error handling** with proper TypeScript types
-- **Consistent error recovery** strategies
-- **Proper error logging** without exposing sensitive data
-- **Graceful degradation** when errors occur
-
-## Principles
-
-1. **Never expose internal details** in user-facing error messages
-2. **Always use type-safe error handling** (no `any` types)
-3. **Log errors appropriately** (with context, without sensitive data)
-4. **Provide recovery paths** when possible
-5. **Use consistent error shapes** across the application
-
-## Error Types
-
-### API Errors
-
-**Shape:**
-```typescript
-type ApiError = {
-  ok: false;
-  error: {
-    code: string;        // Machine-readable error code
-    message: string;     // User-friendly message
-    details?: object;    // Optional additional context (non-sensitive)
-  };
-};
-```
-
-**Example:**
-```typescript
-// ✅ CORRECT
-const result = await apiCall();
-if (!result.ok) {
-  // result.error.message is user-friendly
-  toast.error(result.error.message);
-  logger.error('API call failed', { code: result.error.code, details: result.error.details });
-}
-
-// ❌ WRONG - Exposing internal details
-if (error.message.includes('SQL')) {
-  toast.error(error.message); // Exposes database internals
-}
-```
-
-### Validation Errors
-
-**Shape:**
-```typescript
-type ValidationError = {
-  field: string;
-  message: string;
-  code?: string;
-};
-```
-
-**Example:**
-```typescript
-// ✅ CORRECT - Using Zod validation
-const schema = z.object({
-  email: z.string().email('Please enter a valid email address'),
-  name: z.string().min(1, 'Name is required'),
-});
-
-try {
-  const data = schema.parse(formData);
-} catch (error) {
-  if (error instanceof z.ZodError) {
-    // User-friendly validation messages
-    error.errors.forEach(err => {
-      toast.error(err.message);
-    });
-  }
-}
-```
-
-### Network Errors
-
-**Pattern:**
-```typescript
-// ✅ CORRECT - Handle network errors gracefully
-try {
-  const data = await fetchData();
-} catch (error) {
-  if (error instanceof TypeError && error.message.includes('fetch')) {
-    toast.error('Unable to connect. Please check your internet connection.');
-    logger.error('Network error', { error: error.message });
-  } else {
-    toast.error('An unexpected error occurred. Please try again.');
-    logger.error('Unexpected error', { error });
-  }
-}
-```
-
-## Error Handling Patterns
-
-### Pattern 1: Try-Catch with Type Guards
-
-**Use for:** Known error types that need different handling
-
-```typescript
-// ✅ CORRECT
-function isApiError(error: unknown): error is ApiError {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    'ok' in error &&
-    (error as ApiError).ok === false &&
-    'error' in error
-  );
-}
-
-try {
-  const result = await apiCall();
-  if (!result.ok) {
-    handleApiError(result.error);
-  }
-} catch (error) {
-  if (isApiError(error)) {
-    handleApiError(error.error);
-  } else {
-    handleUnknownError(error);
-  }
-}
-```
-
-### Pattern 2: Result Types
-
-**Use for:** Functions that can fail (preferred pattern)
-
-```typescript
-// ✅ CORRECT - Using Result type
-type Result<T, E = ApiError> = 
-  | { ok: true; data: T }
-  | { ok: false; error: E };
-
-async function fetchUser(id: string): Promise<Result<User>> {
-  try {
-    const { data, error } = await supabase.from('users').select('*').eq('id', id).single();
-    if (error) {
-      return { ok: false, error: { code: 'USER_NOT_FOUND', message: 'User not found' } };
-    }
-    return { ok: true, data };
-  } catch (error) {
-    return { 
-      ok: false, 
-      error: { code: 'UNKNOWN_ERROR', message: 'An unexpected error occurred' } 
-    };
-  }
-}
-
-// Usage
-const result = await fetchUser(userId);
-if (result.ok) {
-  // TypeScript knows result.data exists
-  setUser(result.data);
-} else {
-  // TypeScript knows result.error exists
-  toast.error(result.error.message);
-}
-```
-
-### Pattern 3: Error Boundaries (React)
-
-**Use for:** Catching React component errors
-
-```tsx
-// ✅ CORRECT - Error boundary component
-import { ErrorBoundary } from '@jmruthers/pace-core';
-
-function App() {
-  return (
-    <ErrorBoundary
-      fallback={<ErrorFallback />}
-      onError={(error, errorInfo) => {
-        logger.error('React error boundary caught error', { error, errorInfo });
-      }}
-    >
-      <YourApp />
-    </ErrorBoundary>
-  );
-}
-```
-
-### Pattern 4: Async Error Handling
-
-**Use for:** Async operations with proper error handling
-
-```typescript
-// ✅ CORRECT - Async with error handling
-async function loadData() {
-  try {
-    setIsLoading(true);
-    const result = await fetchData();
-    if (!result.ok) {
-      throw new Error(result.error.message);
-    }
-    setData(result.data);
-  } catch (error) {
-    handleError(error);
-  } finally {
-    setIsLoading(false);
-  }
-}
-```
-
-## Error Messages
-
-### User-Facing Messages
-
-**MUST:**
-- Be user-friendly and actionable
-- Not expose internal details (SQL, stack traces, file paths)
-- Provide context when helpful
-- Be consistent in tone and style
-
-**Examples:**
-```typescript
-// ✅ CORRECT - User-friendly
-'Unable to save changes. Please try again.'
-'This field is required.'
-'Invalid email address format.'
-
-// ❌ WRONG - Exposes internals
-'SQLSTATE[23000]: Integrity constraint violation'
-'Cannot read property "data" of undefined'
-'/app/src/services/api.ts:123:45'
-```
-
-### Logging Messages
-
-**MUST:**
-- Include error context (user ID, operation, etc.)
-- Not log sensitive data (passwords, tokens, PII)
-- Use structured logging when possible
-- Include error codes for correlation
-
-**Examples:**
-```typescript
-// ✅ CORRECT - Structured logging
-logger.error('Failed to save user', {
-  userId: user.id,
-  operation: 'updateUser',
-  errorCode: error.code,
-  timestamp: new Date().toISOString(),
-});
-
-// ❌ WRONG - Logs sensitive data
-logger.error('Failed to save user', {
-  password: user.password, // NEVER log passwords
-  token: authToken,        // NEVER log tokens
-  ssn: user.ssn,          // NEVER log PII
-});
-```
-
-## Error Recovery
-
-### Retry Logic
-
-**Use for:** Transient errors (network, timeouts)
-
-```typescript
-// ✅ CORRECT - Retry with exponential backoff
-async function fetchWithRetry<T>(
-  fn: () => Promise<Result<T>>,
-  maxRetries = 3
-): Promise<Result<T>> {
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    const result = await fn();
-    if (result.ok) {
-      return result;
-    }
-    
-    // Don't retry on client errors (4xx)
-    if (result.error.code?.startsWith('4')) {
-      return result;
-    }
-    
-    // Exponential backoff
-    await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
-  }
-  
-  return { ok: false, error: { code: 'MAX_RETRIES', message: 'Operation failed after retries' } };
-}
-```
-
-### Fallback Values
-
-**Use for:** Non-critical data that can have defaults
-
-```typescript
-// ✅ CORRECT - Fallback to default
-const userPreferences = await fetchUserPreferences().catch(() => ({
-  theme: 'light',
-  language: 'en',
-}));
-```
-
-### Graceful Degradation
-
-**Use for:** Features that can work without optional data
-
-```typescript
-// ✅ CORRECT - Graceful degradation
-async function loadDashboard() {
-  const [events, stats, preferences] = await Promise.allSettled([
-    fetchEvents(),
-    fetchStats(),
-    fetchPreferences(),
-  ]);
-  
-  // Use data that loaded successfully
-  if (events.status === 'fulfilled') {
-    setEvents(events.value);
-  } else {
-    logger.warn('Events failed to load', events.reason);
-    setEvents([]); // Fallback to empty array
-  }
-  
-  // Similar for stats and preferences
-}
-```
-
-## Error Handling Checklist
-
-Before committing code with error handling, verify:
-
-- [ ] User-facing error messages are friendly and actionable
-- [ ] No internal details exposed in user messages
-- [ ] Type-safe error handling (no `any` types)
-- [ ] Errors are logged with context (no sensitive data)
-- [ ] Recovery paths provided when possible
-- [ ] Error shapes are consistent
-- [ ] Error boundaries used for React components
-- [ ] Async operations have proper error handling
-- [ ] Validation errors use Zod or similar
-- [ ] Network errors handled gracefully
-
-## Common Mistakes to Avoid
-
-### ❌ Don't: Expose Internal Details
-
-```typescript
-// ❌ WRONG
-toast.error(error.message); // May contain SQL, stack traces, etc.
-```
-
-### ❌ Don't: Use `any` for Errors
-
-```typescript
-// ❌ WRONG
-catch (error: any) {
-  console.log(error.message);
-}
-```
-
-### ❌ Don't: Log Sensitive Data
-
-```typescript
-// ❌ WRONG
-logger.error('Login failed', { password, token });
-```
-
-### ❌ Don't: Ignore Errors
-
-```typescript
-// ❌ WRONG
-try {
-  await riskyOperation();
-} catch (error) {
-  // Silent failure - user has no idea what happened
-}
-```
-
-### ❌ Don't: Use Generic Messages
-
-```typescript
-// ❌ WRONG
-toast.error('Error occurred'); // Not helpful
-```
-
-## Related Documentation
-
-- [Code Quality Standard](./06-code-quality.md) - TypeScript and code style standards
-- [Security Standard](./01-standards-compliance.md#security-standard) - Security requirements
-- [API & RPC Standard](./01-standards-compliance.md#api--rpc-standard) - API error shapes
-
----
-
-**Last Updated:** 2025-01-28  
-**Version:** 1.0.0  
-**Applies to:** All pace-core and consuming apps
-