swift-state-machine-patterns_skill

Overview

This skill teaches patterns for building type-safe Swift state machines using enum states and action-based transitions. It focuses on making invalid states unrepresentable, separating pure state transitions from side effects, and integrating safely with concurrency and async flows. Practical examples and patterns support lifecycle, protocol, and reentrancy-sensitive logic.

How this skill works

The skill models each machine state as an enum case with associated per-state structs that carry only valid data. Transition methods are pure: they mutate the private state and return typed Action values. Side effects (IO, continuations, task starts) are produced by the transition but executed by a driver outside locks or actor boundaries. Concurrency is handled by extracting continuations or callbacks under a lock and resuming them after releasing the lock.

When to use it

• Protocol or lifecycle logic with strict transition rules
• Reentrancy-sensitive flows (e.g., continuations, rendezvous channels)
• Async or concurrent workflows requiring cancellation safety
• Concurrency boundaries where invalid state must be unrepresentable
• Complex event-driven systems where deterministic testing matters

Best practices

• Model state as an enum with per-state structs and only valid associated data
• Keep the state machine a value type with a private state and pure mutating transitions
• Return actions from transitions and execute side effects in a separate driver
• Use strong typed events, actions, and identifiers — avoid strings/bools for state
• Extract and resume continuations outside locks; use a modifying sentinel to avoid CoW when needed

Example use cases

• Protocol handler that returns actions (send/close/ignore) and driver applies effects
• Channel-style rendezvous for producers/consumers using continuations and suspend/resume actions
• CombineLatest coordination across async sequences with explicit NextAction values
• HTTP/2-style connection state machine with method-per-event transitions
• Lifecycle management where certain operations are only valid in specific states