swift-error-handling

name	swift-error-handling
description	Standards for throwing functions, Result type, and Never. Use when implementing Swift error throwing, designing error hierarchies, using Result types, or adding do-catch blocks.
metadata	{"triggers":{"files":["**/*.swift"],"keywords":["throws","try","catch","Result","Error"]}}

Swift Error Handling

Priority: P0 (CRITICAL)

Workflow: Add Error Handling to Swift Function

1. Define custom error enum conforming to Error
2. Mark function throws (or async throws)
3. Use do-catch at call site with specific catch clauses
4. Map domain errors to user-facing messages at presentation layer

Implementation Guidelines

Throwing Functions

• Propagate Errors: Use throws for recoverable errors and async throws for modern concurrency.
• Do-Catch: Handle close to source; specific catch clauses per error type. Catch-all catch: last resort.
• Error Types: Define custom errors as enums conforming to Error:

See implementation examples for custom error enums, do-catch patterns, and Result type usage.

• Optional Try: Use try? only for non-critical errors where nil acceptable.

Result Type

• Async Alternatives: Use throws for synchronous code. Use Result for callbacks and non-async deferred error states.
• Transformations: Use .map(), .flatMap() for functional composition.
• Conversion: Use .get() to convert Result to throwing for use in try-catch.

Never Type & Preconditions

• Fatalisms: Use Never return type only for unrecoverable crash scenarios or to indicate unreachable code. Never for expected errors.
• Preconditions: Use precondition(), assert(), and fatalError() for programmer errors. Use assertionFailure() for debug-only checks.

Anti-Patterns

• No try!: Use try? or do-catch.
• No try? without nil check: Handle or log.
• No Error(message): Use typed errors.

References

• Error Types & Result

Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:

• Never for expected