groundswell 0.0.2 → 1.0.0

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M2T2S2/research/01_typescript_error_aggregation_patterns.md

@@ -1,789 +0,0 @@
-# TypeScript Error Aggregation Patterns for Promise.allSettled
-
-**Research Date:** 2026-01-12
-**Status:** Comprehensive Research Report
-**Target:** P1M2T2S2 - Error Aggregation Implementation
-
----
-
-## Executive Summary
-
-This document provides comprehensive research on TypeScript error aggregation patterns specifically for Promise.allSettled results. It covers fundamental patterns, type-safe implementations, production-grade strategies, and common pitfalls.
-
-**Key Finding:** TypeScript's type system provides excellent support for Promise.allSettled through discriminated unions and type guards, enabling type-safe error aggregation patterns that preserve both success and failure information.
-
----
-
-## Table of Contents
-
-1. [Fundamental Patterns](#1-fundamental-patterns)
-2. [Type-Safe Implementations](#2-type-safe-implementations)
-3. [Production-Grade Patterns](#3-production-grade-patterns)
-4. [Common Pitfalls](#4-common-pitfalls)
-5. [Best Practices](#5-best-practices)
-6. [Code Examples](#6-code-examples)
-
----
-
-## 1. Fundamental Patterns
-
-### 1.1 Basic Error Collection Pattern
-
-The simplest pattern for collecting errors from Promise.allSettled:
-
-```typescript
-async function executeWithErrorCollection<T>(
-  promises: Promise<T>[]
-): Promise<{ values: T[]; errors: unknown[] }> {
-  const results = await Promise.allSettled(promises);
-
-  const values: T[] = [];
-  const errors: unknown[] = [];
-
-  for (const result of results) {
-    if (result.status === 'fulfilled') {
-      values.push(result.value);
-    } else {
-      errors.push(result.reason);
-    }
-  }
-
-  return { values, errors };
-}
-```
-
-**Key Insights:**
-- Preserves both successful values and errors
-- Returns a structured result for explicit handling
-- Caller decides what to do with errors
-
-**Use Cases:**
-- Bulk operations where partial success is acceptable
-- Data synchronization scenarios
-- Batch processing with retry logic
-
-### 1.2 Filter Pattern
-
-Using array methods to separate successes and failures:
-
-```typescript
-async function executeWithFilter<T>(
-  promises: Promise<T>[]
-): Promise<{ successes: T[]; failures: unknown[] }> {
-  const results = await Promise.allSettled(promises);
-
-  const successes = results
-    .filter((r): r is PromiseFulfilledResult<T> => r.status === 'fulfilled')
-    .map(r => r.value);
-
-  const failures = results
-    .filter((r): r is PromiseRejectedResult => r.status === 'rejected')
-    .map(r => r.reason);
-
-  return { successes, failures };
-}
-```
-
-**Key Insights:**
-- Uses TypeScript type guards for type narrowing
-- Cleaner separation of concerns
-- More functional programming style
-
-**Use Cases:**
-- When you need separate arrays for successes and failures
-- When you want to process successes and failures differently
-- Reporting and analytics scenarios
-
-### 1.3 Reduce Pattern
-
-Using reduce to accumulate results in a single pass:
-
-```typescript
-async function executeWithReduce<T>(
-  promises: Promise<T>[]
-): Promise<{ successes: T[]; failures: unknown[]; stats: { total: number; succeeded: number; failed: number } }> {
-  const results = await Promise.allSettled(promises);
-
-  const { successes, failures, stats } = results.reduce<{
-    successes: T[];
-    failures: unknown[];
-    stats: { total: number; succeeded: number; failed: number };
-  }>(
-    (acc, result) => {
-      acc.stats.total++;
-
-      if (result.status === 'fulfilled') {
-        acc.successes.push(result.value);
-        acc.stats.succeeded++;
-      } else {
-        acc.failures.push(result.reason);
-        acc.stats.failed++;
-      }
-
-      return acc;
-    },
-    { successes: [], failures: [], stats: { total: 0, succeeded: 0, failed: 0 } }
-  );
-
-  return { successes, failures, stats };
-}
-```
-
-**Key Insights:**
-- Single pass through results (more efficient)
-- Builds statistics alongside collection
-- Useful for monitoring and analytics
-
-**Use Cases:**
-- When you need statistics along with results
-- Performance-critical scenarios with large arrays
-- Real-time monitoring and reporting
-
----
-
-## 2. Type-Safe Implementations
-
-### 2.1 Type Guards for PromiseSettledResult
-
-TypeScript requires type guards to properly narrow PromiseSettledResult types:
-
-```typescript
-// Type guard for fulfilled results
-function isFulfilled<T>(result: PromiseSettledResult<T>): result is PromiseFulfilledResult<T> {
-  return result.status === 'fulfilled';
-}
-
-// Type guard for rejected results
-function isRejected<T>(result: PromiseSettledResult<T>): result is PromiseRejectedResult {
-  return result.status === 'rejected';
-}
-
-// Usage
-const results = await Promise.allSettled(promises);
-
-// Without type guard - TypeScript error
-// results.filter(r => r.status === 'fulfilled').map(r => r.value); // ERROR
-
-// With type guard - TypeScript knows value exists
-const successes = results.filter(isFulfilled).map(r => r.value);
-const failures = results.filter(isRejected).map(r => r.reason);
-```
-
-**Key Insights:**
-- Type guards are essential for type safety
-- TypeScript cannot narrow types without explicit type predicates
-- Reusable type guards improve code consistency
-
-### 2.2 Discriminated Union Pattern
-
-Create a custom discriminated union for better type safety:
-
-```typescript
-type SettledResult<T, E = Error> =
-  | { status: 'fulfilled'; value: T }
-  | { status: 'rejected'; error: E };
-
-async function executeWithDiscriminatedUnion<T>(
-  promises: Promise<T>[]
-): Promise<SettledResult<T, Error>[]> {
-  const results = await Promise.allSettled(promises);
-
-  return results.map(result => {
-    if (result.status === 'fulfilled') {
-      return { status: 'fulfilled' as const, value: result.value };
-    } else {
-      const reason = result.reason;
-      const error = reason instanceof Error ? reason : new Error(String(reason));
-      return { status: 'rejected' as const, error };
-    }
-  });
-}
-
-// Type-safe usage
-for (const result of await executeWithDiscriminatedUnion(promises)) {
-  if (result.status === 'fulfilled') {
-    console.log(result.value); // TypeScript knows this is T
-  } else {
-    console.error(result.error.message); // TypeScript knows this is Error
-  }
-}
-```
-
-**Key Insights:**
-- Custom discriminated unions provide better type safety
-- Normalizes non-Error rejections to Error objects
-- More explicit and self-documenting than PromiseSettledResult
-
-### 2.3 Generic Error Aggregation Type
-
-Create a reusable generic type for error aggregation:
-
-```typescript
-type ExecutionResult<T, E = Error> = {
-  successes: T[];
-  failures: Array<{ index: number; error: E }>;
-  stats: {
-    total: number;
-    succeeded: number;
-    failed: number;
-    errorRate: number;
-  };
-};
-
-async function executeWithTypedErrors<T, E = Error>(
-  promises: Promise<T>[]
-): Promise<ExecutionResult<T, E>> {
-  const results = await Promise.allSettled(promises);
-
-  const successes: T[] = [];
-  const failures: Array<{ index: number; error: E }> = [];
-
-  results.forEach((result, index) => {
-    if (result.status === 'fulfilled') {
-      successes.push(result.value);
-    } else {
-      const reason = result.reason;
-      const error = reason instanceof Error ? (reason as E) : new Error(String(reason)) as E;
-      failures.push({ index, error });
-    }
-  });
-
-  const stats = {
-    total: results.length,
-    succeeded: successes.length,
-    failed: failures.length,
-    errorRate: failures.length / results.length,
-  };
-
-  return { successes, failures, stats };
-}
-```
-
-**Key Insights:**
-- Generic types enable reusability across different scenarios
-- Preserves index information for debugging
-- Includes statistics for monitoring
-
----
-
-## 3. Production-Grade Patterns
-
-### 3.1 Contextual Error Aggregation
-
-Associate errors with their source operations:
-
-```typescript
-interface Operation<T> {
-  id: string;
-  name: string;
-  promise: Promise<T>;
-}
-
-interface OperationResult<T, E = Error> {
-  operation: { id: string; name: string };
-  status: 'fulfilled' | 'rejected';
-  value?: T;
-  error?: E;
-}
-
-async function executeWithContext<T>(
-  operations: Operation<T>[]
-): Promise<OperationResult<T>[]> {
-  const promises = operations.map(op => op.promise);
-  const results = await Promise.allSettled(promises);
-
-  return operations.map((operation, index) => {
-    const result = results[index];
-
-    if (result.status === 'fulfilled') {
-      return {
-        operation: { id: operation.id, name: operation.name },
-        status: 'fulfilled',
-        value: result.value,
-      };
-    } else {
-      const reason = result.reason;
-      const error = reason instanceof Error ? reason : new Error(String(reason));
-      return {
-        operation: { id: operation.id, name: operation.name },
-        status: 'rejected',
-        error,
-      };
-    }
-  });
-}
-```
-
-**Key Insights:**
-- Preserves operation context (id, name) with results
-- Critical for debugging and logging
-- Enables detailed error reporting
-
-**Use Cases:**
-- Batch API calls with different endpoints
-- Multi-step workflows
-- Parallel data processing with different sources
-
-### 3.2 Error Rate Thresholding
-
-Implement threshold-based error handling:
-
-```typescript
-interface ThresholdOptions {
-  maxErrorRate: number; // 0.0 to 1.0
-  minAbsoluteErrors: number;
-  onThresholdExceeded?: (stats: { errorRate: number; failed: number; total: number }) => void;
-}
-
-async function executeWithThreshold<T>(
-  promises: Promise<T>[],
-  options: ThresholdOptions
-): Promise<{ successes: T[]; failures: unknown[]; exceededThreshold: boolean }> {
-  const results = await Promise.allSettled(promises);
-
-  const successes = results
-    .filter((r): r is PromiseFulfilledResult<T> => r.status === 'fulfilled')
-    .map(r => r.value);
-
-  const failures = results
-    .filter((r): r is PromiseRejectedResult => r.status === 'rejected')
-    .map(r => r.reason);
-
-  const errorRate = failures.length / results.length;
-  const exceededThreshold =
-    failures.length >= options.minAbsoluteErrors ||
-    errorRate > options.maxErrorRate;
-
-  if (exceededThreshold && options.onThresholdExceeded) {
-    options.onThresholdExceeded({
-      errorRate,
-      failed: failures.length,
-      total: results.length,
-    });
-  }
-
-  return { successes, failures, exceededThreshold };
-}
-```
-
-**Key Insights:**
-- Allows some failures without throwing
-- Configurable tolerance levels
-- Useful for graceful degradation
-
-**Use Cases:**
-- High-volume operations where some failures are acceptable
-- Cache warming
-- Bulk notifications
-- Data replication
-
-### 3.3 Hierarchical Error Aggregation
-
-Aggregate errors with hierarchical context:
-
-```typescript
-interface HierarchicalError {
-  message: string;
-  errors: Array<{
-    operationId: string;
-    operationName: string;
-    error: Error;
-    timestamp: number;
-  }>;
-  parentContext?: {
-    workflowId: string;
-    workflowName: string;
-  };
-  stats: {
-    totalErrors: number;
-    errorsByOperation: Record<string, number>;
-    errorsByType: Record<string, number>;
-  };
-}
-
-async function executeWithHierarchicalErrors<T>(
-  operations: Array<{ id: string; name: string; promise: Promise<T> }>,
-  parentContext?: { workflowId: string; workflowName: string }
-): Promise<{ successes: T[]; aggregatedError?: HierarchicalError }> {
-  const results = await Promise.allSettled(operations.map(op => op.promise));
-
-  const successes: T[] = [];
-  const errors: Array<{
-    operationId: string;
-    operationName: string;
-    error: Error;
-    timestamp: number;
-  }> = [];
-
-  operations.forEach((op, index) => {
-    const result = results[index];
-
-    if (result.status === 'fulfilled') {
-      successes.push(result.value);
-    } else {
-      const reason = result.reason;
-      const error = reason instanceof Error ? reason : new Error(String(reason));
-      errors.push({
-        operationId: op.id,
-        operationName: op.name,
-        error,
-        timestamp: Date.now(),
-      });
-    }
-  });
-
-  if (errors.length > 0) {
-    const errorsByOperation: Record<string, number> = {};
-    const errorsByType: Record<string, number> = {};
-
-    errors.forEach(err => {
-      errorsByOperation[err.operationName] = (errorsByOperation[err.operationName] || 0) + 1;
-      const errorType = err.error.constructor.name;
-      errorsByType[errorType] = (errorsByType[errorType] || 0) + 1;
-    });
-
-    const aggregatedError: HierarchicalError = {
-      message: `${errors.length} operation(s) failed`,
-      errors,
-      parentContext,
-      stats: {
-        totalErrors: errors.length,
-        errorsByOperation,
-        errorsByType,
-      },
-    };
-
-    return { successes, aggregatedError };
-  }
-
-  return { successes };
-}
-```
-
-**Key Insights:**
-- Maintains full error hierarchy
-- Provides error statistics and categorization
-- Excellent for debugging and monitoring
-
-**Use Cases:**
-- Complex workflow engines
-- Distributed systems
-- Microservice orchestration
-
----
-
-## 4. Common Pitfalls
-
-### 4.1 Forgetting Type Guards
-
-**Problem:** Not using type guards causes type narrowing issues.
-
-```typescript
-// ❌ WRONG - TypeScript error
-const results = await Promise.allSettled(promises);
-const successes = results.filter(r => r.status === 'fulfilled');
-successes.forEach(s => {
-  console.log(s.value); // TypeScript error: value might not exist
-});
-
-// ✅ CORRECT - Use type guard
-function isFulfilled<T>(result: PromiseSettledResult<T>): result is PromiseFulfilledResult<T> {
-  return result.status === 'fulfilled';
-}
-
-const results = await Promise.allSettled(promises);
-const successes = results.filter(isFulfilled);
-successes.forEach(s => {
-  console.log(s.value); // TypeScript knows value exists
-});
-```
-
-### 4.2 Losing Error Context
-
-**Problem:** Not capturing which operation failed makes debugging difficult.
-
-```typescript
-// ❌ WRONG - Don't know which promise failed
-const results = await Promise.allSettled([
-  fetch('/api/users'),
-  fetch('/api/posts'),
-  fetch('/api/comments')
-]);
-
-// ✅ CORRECT - Associate results with operations
-const operations = [
-  { name: 'users', promise: fetch('/api/users') },
-  { name: 'posts', promise: fetch('/api/posts') },
-  { name: 'comments', promise: fetch('/api/comments') }
-];
-
-const results = await Promise.allSettled(operations.map(op => op.promise));
-
-const failures = operations
-  .map((op, i) => ({ ...op, result: results[i] }))
-  .filter(({ result }) => result.status === 'rejected')
-  .map(({ name, result }) => ({
-    operation: name,
-    error: (result as PromiseRejectedResult).reason
-  }));
-```
-
-### 4.3 Not Handling Non-Error Rejections
-
-**Problem:** Promises can reject with non-Error values.
-
-```typescript
-// Promise.reject can reject with anything
-const results = await Promise.allSettled([
-  Promise.reject('string error'),
-  Promise.reject(123),
-  Promise.reject(null),
-  Promise.reject(undefined)
-]);
-
-// ✅ CORRECT - Handle non-Error rejections
-const normalizedErrors = results
-  .filter(r => r.status === 'rejected')
-  .map(r => {
-    const reason = (r as PromiseRejectedResult).reason;
-    if (reason instanceof Error) {
-      return reason;
-    }
-    return new Error(String(reason ?? 'Unknown error'));
-  });
-```
-
-### 4.4 Memory Issues with Large Arrays
-
-**Problem:** Storing all results can consume significant memory.
-
-```typescript
-// ❌ PROBLEMATIC - Stores all results in memory
-const results = await Promise.allSettled(largeArrayOfPromises);
-
-// ✅ BETTER - Process results in batches
-async function processBatch<T>(
-  promises: Promise<T>[],
-  batchSize: number,
-  processor: (results: PromiseSettledResult<T>[]) => void
-) {
-  for (let i = 0; i < promises.length; i += batchSize) {
-    const batch = promises.slice(i, i + batchSize);
-    const results = await Promise.allSettled(batch);
-    processor(results);
-    // Allow GC to clean up batch results
-  }
-}
-```
-
----
-
-## 5. Best Practices
-
-### 5.1 Always Use Type Guards
-
-```typescript
-// Reusable type guards
-export const PromiseSettledHelpers = {
-  isFulfilled<T>(result: PromiseSettledResult<T>): result is PromiseFulfilledResult<T> {
-    return result.status === 'fulfilled';
-  },
-
-  isRejected<T>(result: PromiseSettledResult<T>): result is PromiseRejectedResult {
-    return result.status === 'rejected';
-  },
-
-  filterFulfilled<T>(results: PromiseSettledResult<T>[]): T[] {
-    return results.filter(this.isFulfilled).map(r => r.value);
-  },
-
-  filterRejected<T>(results: PromiseSettledResult<T>[]): unknown[] {
-    return results.filter(this.isRejected).map(r => r.reason);
-  },
-};
-```
-
-### 5.2 Preserve Operation Context
-
-Always associate results with their source operations:
-
-```typescript
-interface ContextualResult<T, E = Error> {
-  operationId: string;
-  operationName: string;
-  status: 'fulfilled' | 'rejected';
-  value?: T;
-  error?: E;
-}
-
-async function executeWithContext<T>(
-  operations: Array<{ id: string; name: string; promise: Promise<T> }>
-): Promise<ContextualResult<T>[]> {
-  // Implementation from section 3.1
-}
-```
-
-### 5.3 Normalize Errors
-
-Always normalize non-Error rejections to Error objects:
-
-```typescript
-function normalizeError(reason: unknown): Error {
-  if (reason instanceof Error) {
-    return reason;
-  }
-  if (reason === null || reason === undefined) {
-    return new Error('Unknown error');
-  }
-  return new Error(String(reason));
-}
-```
-
-### 5.4 Provide Statistics
-
-Include statistics for monitoring and debugging:
-
-```typescript
-interface ExecutionStats {
-  total: number;
-  succeeded: number;
-  failed: number;
-  errorRate: number;
-  duration: number;
-}
-```
-
----
-
-## 6. Code Examples
-
-### 6.1 Complete Example: Batch API Calls
-
-```typescript
-interface ApiCall {
-  id: string;
-  name: string;
-  url: string;
-}
-
-interface ApiResult {
-  id: string;
-  name: string;
-  status: number;
-  data?: unknown;
-  error?: Error;
-}
-
-async function batchApiCalls(calls: ApiCall[]): Promise<{
-  successes: ApiResult[];
-  failures: ApiResult[];
-  stats: { total: number; succeeded: number; failed: number; errorRate: number };
-}> {
-  const operations = calls.map(call => ({
-    id: call.id,
-    name: call.name,
-    promise: fetch(call.url).then(res => ({
-      id: call.id,
-      name: call.name,
-      status: res.status,
-      data: res.ok ? await res.json() : undefined,
-    })),
-  }));
-
-  const results = await Promise.allSettled(operations.map(op => op.promise));
-
-  const successes: ApiResult[] = [];
-  const failures: ApiResult[] = [];
-
-  operations.forEach((op, index) => {
-    const result = results[index];
-
-    if (result.status === 'fulfilled') {
-      successes.push(result.value);
-    } else {
-      failures.push({
-        id: op.id,
-        name: op.name,
-        status: 0,
-        error: result.reason instanceof Error ? result.reason : new Error(String(result.reason)),
-      });
-    }
-  });
-
-  const stats = {
-    total: results.length,
-    succeeded: successes.length,
-    failed: failures.length,
-    errorRate: failures.length / results.length,
-  };
-
-  return { successes, failures, stats };
-}
-```
-
-### 6.2 Complete Example: Workflow Error Aggregation
-
-```typescript
-interface WorkflowError {
-  workflowId: string;
-  workflowName: string;
-  error: Error;
-  timestamp: number;
-}
-
-interface WorkflowAggregateError extends Error {
-  name: 'WorkflowAggregateError';
-  message: string;
-  errors: WorkflowError[];
-  parentWorkflowId: string;
-  totalChildren: number;
-  failedChildren: number;
-}
-
-function createWorkflowAggregateError(
-  errors: WorkflowError[],
-  parentWorkflowId: string,
-  totalChildren: number
-): WorkflowAggregateError {
-  const error = new Error(
-    `${errors.length} child workflow(s) failed`
-  ) as WorkflowAggregateError;
-
-  error.name = 'WorkflowAggregateError';
-  error.errors = errors;
-  error.parentWorkflowId = parentWorkflowId;
-  error.totalChildren = totalChildren;
-  error.failedChildren = errors.length;
-
-  return error;
-}
-```
-
----
-
-## References
-
-### TypeScript Documentation
-1. TypeScript Handbook: Type Guards - https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates
-2. TypeScript Handbook: Discriminated Unions - https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions
-3. PromiseSettledResult Type - https://www.typescriptlang.org/docs/handbook/2/types-from-types.html#promise-types
-
-### MDN Documentation
-4. Promise.allSettled() - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled
-5. Using Promises - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises
-
-### Community Resources
-6. StackOverflow: TypeScript Promise.allSettled typing - https://stackoverflow.com/questions/60191992
-7. StackOverflow: Type guards for PromiseSettledResult - https://stackoverflow.com/questions/60386810
-
-### Groundswell-Specific
-8. Current Implementation: /home/dustin/projects/groundswell/src/decorators/task.ts
-9. Error Strategy Types: /home/dustin/projects/groundswell/src/types/error-strategy.ts
-10. WorkflowError Interface: /home/dustin/projects/groundswell/src/types/error.ts
-
----
-
-**Document Version:** 1.0
-**Last Updated:** 2026-01-12
-**Status:** Complete
-**Next Review:** After P1M2T2S2 Implementation