@jmruthers/pace-core 0.6.4 → 0.6.6

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

@@ -0,0 +1,401 @@
+# 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
+