breaking: Throw error on empty concatenate, remove force cast

[takeshishimada]

Summary

Make ActionTask.concatenate() throw FlowError.noTasksToExecute when given an empty array, implementing the fail-fast principle for better error detection. This change completely removes the force cast from Store.swift.

Problem

The current implementation has a critical flaw:

// Store.swift:352 - Force cast with runtime type check
guard let result = lastResult else {
  if F.ActionResult.self is Void.Type {
    return (() as! F.ActionResult)  // ❌ Force cast
  }
  throw StoreError.cancelled
}

This code is actually unreachable because:

1. concatenate([]) calls fatalError (crashes app)
2. Therefore empty concatenated tasks never reach Store

The force cast exists to handle a case that cannot occur.

Root Cause Analysis

Empty task arrays indicate one of two scenarios:

1. Logic error (bug) - Tasks were expected but none generated
2. Valid business logic - Empty collection is normal (e.g., no items to process)

Current fatalError approach:

• ❌ Crashes production apps
• ❌ No error message or context
• ❌ Cannot recover
• ❌ Difficult to debug

Solution: Throw Typed Error

Changes

1. New Error Case

// FlowError.swift
case noTasksToExecute(context: String? = nil)

With comprehensive documentation:

• Clear error message
• Recovery suggestions
• Debugging guidance

2. Make concatenate() Throwing

// ActionTask.swift
public static func concatenate(_ tasks: [ActionTask]) throws -> ActionTask {
  guard let first = tasks.first else {
    throw FlowError.noTasksToExecute(context: "concatenate(_:)")
  }
  return tasks.dropFirst().reduce(first) { $0.concatenate(with: $1) }
}

3. Remove Force Cast

// Store.swift
case .concatenated:
  let tasks = task.flattenConcatenated()
  
  // INVARIANT: Always ≥1 element (empty throws at construction)
  precondition(!tasks.isEmpty, "concatenated task list is empty")
  
  var lastResult = try await self.executeTask(tasks[0])
  
  for task in tasks.dropFirst() {
    lastResult = try await self.executeTask(task)
  }
  
  return lastResult  // ✅ No force cast!

Benefits

1. Fail Fast

let tasks = buildTasks()  // Bug: returns []
return try .concatenate(tasks)  // ✅ Throws immediately with clear message

2. Explicit Intent

// Developer must explicitly handle empty case
guard !tasks.isEmpty else {
  return .none  // "Empty is valid" - explicit
}
return try .concatenate(tasks)

3. Recoverable Errors

ActionHandler { action, state in
  return try .concatenate(tasks)
}
.catch { error, state in
  if case FlowError.noTasksToExecute = error {
    state.message = "No items to process"
  }
}

4. Type Safety

• Works for all ActionResult types (not just Void)
• No runtime type checking
• Compile-time safety

5. Better Debugging

Error: No tasks to execute in concatenate(_:). Empty task arrays are not allowed.

Recovery Suggestion:
guard !tasks.isEmpty else {
  return .none
}
return try .concatenate(tasks)

Migration Guide

Before

let tasks = items.map { ... }
return .concatenate(tasks)  // Crashes if empty

After - Option 1: Explicit Guard

let tasks = items.map { ... }
guard !tasks.isEmpty else {
  return .none  // Empty is intentional
}
return try .concatenate(tasks)

After - Option 2: Propagate Error

let tasks = items.map { ... }
return try .concatenate(tasks)  // Error propagates to .catch

Variadic Version (Non-Breaking)

// Still safe - compile-time guaranteed non-empty
return .concatenate(
  .run { ... },
  .run { ... }
)

Breaking Changes

⚠️ This is a breaking change for v2.0

• ActionTask.concatenate([ActionTask]) now throws
• Callers must add try or guard

Testing

• ✅ All 299 tests pass
• ✅ No existing code used empty concatenate
• ✅ Force cast completely removed
• ✅ SwiftLint clean

Technical Details

Why Throw Instead of Returning .none?

1. Fail Fast Principle: Bugs should be loud, not silent
2. Swift Philosophy: Use try to mark dangerous operations
3. Type Safety: Works for all ActionResult types
4. Explicit Intent: Forces developers to think about empty case

Why This is Safe:

The invariant is enforced at construction time:

• concatenate([]) throws before creating .concatenated
• Therefore .concatenated always contains ≥1 task
• flattenConcatenated() preserves this property
• precondition documents and verifies this invariant

🤖 Generated with Claude Code