devflow-kit 0.9.0 → 1.0.0

package/shared/skills/complexity-patterns/references/patterns.md

@@ -0,0 +1,487 @@
+# Complexity Resolution Patterns
+
+Correct patterns for addressing complexity issues.
+
+---
+
+## Deep Nesting Solutions
+
+### Early Returns
+
+```typescript
+// Extract nested conditionals with early returns
+function processOrder(order: Order) {
+  if (!order?.items) return;
+
+  for (const item of order.items) {
+    processItem(item);
+  }
+}
+
+function processItem(item: OrderItem) {
+  if (item.quantity <= 0) return;
+  if (!item.product?.inStock) return;
+
+  // Actual logic at top level
+}
+```
+
+### Guard Clauses
+
+```typescript
+// Validate preconditions first
+async function updateUser(userId: string, data: UpdateData) {
+  // Guards at the top
+  if (!userId) return Err({ type: 'InvalidInput', field: 'userId' });
+  if (!data) return Err({ type: 'InvalidInput', field: 'data' });
+
+  const user = await userRepo.findById(userId);
+  if (!user) return Err({ type: 'NotFound', id: userId });
+  if (!user.canBeUpdated) return Err({ type: 'Forbidden' });
+
+  // Happy path at normal indentation
+  const updated = { ...user, ...data };
+  return Ok(await userRepo.save(updated));
+}
+```
+
+### Extract and Compose
+
+```typescript
+// Break nested try-catch into composed functions
+async function fetchAndProcess(url: string): Promise<Result<void, Error>> {
+  const response = await safeFetch(url);
+  if (!response.ok) return response;
+
+  const data = await safeParseJson(response.value);
+  if (!data.ok) return data;
+
+  return processItems(data.value.items);
+}
+
+async function safeFetch(url: string): Promise<Result<Response, Error>> {
+  try {
+    const response = await fetch(url);
+    if (!response.ok) return Err(new Error(`HTTP ${response.status}`));
+    return Ok(response);
+  } catch (error) {
+    return Err(error as Error);
+  }
+}
+```
+
+---
+
+## Long Function Solutions
+
+### Extract Logical Units
+
+```typescript
+// Break monolithic function into composed steps
+async function handleCheckout(cart: Cart, user: User) {
+  const validated = validateCart(cart);
+  const priced = calculatePricing(validated);
+  const reserved = await reserveInventory(priced);
+  const payment = await processPayment(reserved, user);
+  await sendNotifications(payment);
+  trackAnalytics(payment);
+  return payment;
+}
+```
+
+### Pipeline Pattern
+
+```typescript
+// Chain transformations clearly
+async function userRegistrationFlow(formData: FormData): Promise<Result<User, Error>> {
+  return pipe(
+    formData,
+    validateFormData,
+    sanitizeInput,
+    checkForDuplicates,
+    hashPassword,
+    createUserRecord,
+    sendVerificationEmail,
+    createSession
+  );
+}
+```
+
+### Command Pattern
+
+```typescript
+// Encapsulate each step as a command
+class CheckoutProcessor {
+  private steps: CheckoutStep[] = [
+    new ValidateCartStep(),
+    new CalculatePricingStep(),
+    new ReserveInventoryStep(),
+    new ProcessPaymentStep(),
+    new SendNotificationsStep(),
+  ];
+
+  async process(cart: Cart, user: User): Promise<CheckoutResult> {
+    let context = { cart, user };
+    for (const step of this.steps) {
+      const result = await step.execute(context);
+      if (!result.ok) return result;
+      context = result.value;
+    }
+    return Ok(context);
+  }
+}
+```
+
+---
+
+## High Cyclomatic Complexity Solutions
+
+### Data-Driven Approach
+
+```typescript
+// Replace decision tree with lookup
+const categoryRules: Record<string, (item: Item) => string> = {
+  'A': categorizeTypeA,
+  'B': categorizeTypeB,
+  'C': categorizeTypeC,
+};
+
+function categorize(item: Item): string {
+  const handler = categoryRules[item.type];
+  return handler ? handler(item) : 'unknown';
+}
+
+function categorizeTypeA(item: Item): string {
+  const size = item.size > 10 ? 'large' : 'small';
+  const color = item.color || 'other';
+  return `A-${size}-${color}`;
+}
+```
+
+### Strategy Pattern
+
+```typescript
+// Encapsulate variants in classes
+interface EventHandler {
+  canHandle(event: Event): boolean;
+  handle(event: Event): Promise<void>;
+}
+
+class UserCreatedHandler implements EventHandler {
+  canHandle(event: Event) { return event.type === 'USER_CREATED'; }
+  async handle(event: Event) { /* focused logic */ }
+}
+
+class EventProcessor {
+  constructor(private handlers: EventHandler[]) {}
+
+  async process(event: Event) {
+    const handler = this.handlers.find(h => h.canHandle(event));
+    if (handler) await handler.handle(event);
+  }
+}
+```
+
+### Polymorphism
+
+```typescript
+// Use type system to eliminate conditionals
+abstract class User {
+  abstract getPermissions(): Permission[];
+  abstract canAccessResource(resource: Resource): boolean;
+}
+
+class AdminUser extends User {
+  getPermissions() { return ALL_PERMISSIONS; }
+  canAccessResource() { return true; }
+}
+
+class RegularUser extends User {
+  getPermissions() { return BASIC_PERMISSIONS; }
+  canAccessResource(resource: Resource) {
+    return resource.isPublic || this.owns(resource);
+  }
+}
+```
+
+---
+
+## Magic Value Solutions
+
+### Named Constants
+
+```typescript
+// Extract literals to named constants
+const OrderStatus = {
+  PENDING: 1,
+  PROCESSING: 2,
+  COMPLETED: 3,
+} as const;
+
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const MAX_RETRIES = 5;
+
+if (status === OrderStatus.COMPLETED) {
+  setTimeout(callback, ONE_DAY_MS);
+  retry(MAX_RETRIES);
+}
+```
+
+### Configuration Objects
+
+```typescript
+// Centralize business rules
+const ShippingRates = {
+  HEAVY_ITEM_THRESHOLD: 50,      // kg
+  LONG_DISTANCE_THRESHOLD: 500,  // km
+  rates: {
+    heavy: 29.99,
+    longDistance: 19.99,
+    bulky: 24.99,
+    standard: 9.99,
+  }
+} as const;
+
+function calculateShipping(weight: number, distance: number): number {
+  if (weight > ShippingRates.HEAVY_ITEM_THRESHOLD) return ShippingRates.rates.heavy;
+  if (distance > ShippingRates.LONG_DISTANCE_THRESHOLD) return ShippingRates.rates.longDistance;
+  return ShippingRates.rates.standard;
+}
+```
+
+---
+
+## Complex Expression Solutions
+
+### Break Into Named Steps
+
+```typescript
+// Replace chained operations with named steps
+const activePremiumUsers = data.filter(isActivePremium);
+const withScores = activePremiumUsers.map(calculateScore);
+const topScore = findHighestScore(withScores);
+
+function isActivePremium(user: User) {
+  return user.active && user.type === 'premium';
+}
+
+function calculateScore(user: User) {
+  const multiplier = user.bonus ? 1.5 : 1;
+  return { ...user, score: (user.points * multiplier) / user.level };
+}
+
+function findHighestScore(users: ScoredUser[]) {
+  return users.sort((a, b) => b.score - a.score)[0]?.score ?? 0;
+}
+```
+
+### Replace Ternary Chains
+
+```typescript
+// Use mapping or switch for multiple conditions
+function getUserStatus(user: User): string {
+  if (user.isAdmin) return 'admin';
+  if (user.isModerator) return 'moderator';
+  if (user.isVerified) return 'verified';
+  if (user.isPending) return 'pending';
+  return 'guest';
+}
+
+// Or use a lookup
+const statusPriority = [
+  { check: (u: User) => u.isAdmin, status: 'admin' },
+  { check: (u: User) => u.isModerator, status: 'moderator' },
+  { check: (u: User) => u.isVerified, status: 'verified' },
+  { check: (u: User) => u.isPending, status: 'pending' },
+];
+
+function getUserStatus(user: User): string {
+  return statusPriority.find(p => p.check(user))?.status ?? 'guest';
+}
+```
+
+---
+
+## Naming Solutions
+
+### Descriptive Names
+
+```typescript
+// Replace cryptic with descriptive
+const now = new Date();
+const oneDayAgo = now.getTime() - ONE_DAY_MS;
+const recentItems = items.filter(item => item.timestamp > oneDayAgo);
+const totalPrice = recentItems.reduce((sum, item) => sum + item.price, 0);
+```
+
+### Intent-Revealing Names
+
+```typescript
+// Name functions by what they do
+function findOverdueInvoices(invoices: Invoice[]): Invoice[] {
+  const thirtyDaysAgo = subDays(new Date(), 30);
+  return invoices.filter(inv => inv.dueDate < thirtyDaysAgo && !inv.paid);
+}
+
+// Not: function process(data) or function filter(items)
+```
+
+---
+
+## Code Duplication Solutions
+
+### Generic Validation Framework
+
+```typescript
+// Extract common pattern
+type ValidationRule<T> = (value: T) => string | null;
+
+function validate<T>(value: T, rules: ValidationRule<T>[]): ValidationResult {
+  for (const rule of rules) {
+    const error = rule(value);
+    if (error) return { valid: false, error };
+  }
+  return { valid: true, error: null };
+}
+
+const required = (v: string) => v ? null : 'Required';
+const minLength = (n: number) => (v: string) => v.length >= n ? null : 'Too short';
+const isEmail = (v: string) => v.includes('@') ? null : 'Invalid format';
+
+const validateEmail = (email: string) => validate(email, [required, isEmail]);
+const validateUsername = (name: string) => validate(name, [required, minLength(3)]);
+```
+
+### Generic Resource Handler
+
+```typescript
+// Abstract the common pattern
+function createResourceHandler<T>(
+  tableName: string,
+  findById: (id: string) => Promise<T | null>
+) {
+  return async (req: Request, res: Response) => {
+    try {
+      const entity = await findById(req.params.id);
+      if (!entity) return res.status(404).json({ error: 'Not found' });
+      res.json(entity);
+    } catch (error) {
+      res.status(500).json({ error: 'Internal error' });
+    }
+  };
+}
+
+app.get('/users/:id', createResourceHandler('users', db.users.findById));
+app.get('/orders/:id', createResourceHandler('orders', db.orders.findById));
+```
+
+---
+
+## Parameter List Solutions
+
+### Object Parameter
+
+```typescript
+// Group related parameters
+interface CreateUserParams {
+  name: string;
+  email: string;
+  password: string;
+  role: string;
+  department: string;
+  manager?: string;
+  startDate: Date;
+  salary: number;
+  benefits?: string[];
+}
+
+function createUser(params: CreateUserParams) {
+  // ...
+}
+```
+
+### Options Object for Booleans
+
+```typescript
+// Replace boolean flags with named options
+interface FormatOptions {
+  includeHeader?: boolean;
+  includeFooter?: boolean;
+  useColor?: boolean;
+  landscape?: boolean;
+  doubleSided?: boolean;
+}
+
+function formatDocument(doc: Document, options: FormatOptions = {}) {
+  // ...
+}
+
+// Call site is clear:
+formatDocument(doc, { useColor: true, doubleSided: true });
+```
+
+---
+
+## Boolean Complexity Solutions
+
+### Extract Named Predicates
+
+```typescript
+// Replace complex boolean with readable function
+const canModerate = (user: User): boolean => {
+  if (!user.active || user.deleted) return false;
+  if (!['admin', 'moderator'].includes(user.role)) return false;
+  if (!user.verified) return false;
+  if (user.suspended && user.suspendedUntil >= Date.now()) return false;
+  return true;
+};
+
+if (canModerate(user)) {
+  // ...
+}
+```
+
+### Positive Conditions
+
+```typescript
+// Eliminate double negatives
+// Before: if (!user.isNotActive && !items.isEmpty())
+// After:
+if (user.isActive && items.length > 0) {
+  // ...
+}
+
+// Apply De Morgan's law and simplify
+// Before: if (!(a && !b) || !(!c || d))
+// After:
+if (!a || b || (c && !d)) {
+  // ...
+}
+```
+
+---
+
+## Shotgun Surgery Solutions
+
+### Encapsulate Variation
+
+```typescript
+// Adding new type = one new class
+interface UserTypeHandler {
+  validate(data: UserData): ValidationResult;
+  serialize(user: User): SerializedUser;
+  getPermissions(): Permission[];
+}
+
+class AdminUserHandler implements UserTypeHandler { /* ... */ }
+class RegularUserHandler implements UserTypeHandler { /* ... */ }
+class GuestUserHandler implements UserTypeHandler { /* ... */ }
+
+// Registry for handlers
+const handlers = new Map<UserType, UserTypeHandler>();
+handlers.set('admin', new AdminUserHandler());
+handlers.set('regular', new RegularUserHandler());
+handlers.set('guest', new GuestUserHandler());
+
+// Adding new type: just add one new class and register it
+```