Atoms: Atomic State Management for SwiftUI

While the library defaults to a single source of truth, you can isolate atom state using AtomScope and the Scoped attribute.

Scoped Atoms

An atom marked with the Scoped attribute will preserve its state within the nearest AtomScope ancestor. This prevents the state from being shared with atoms outside that scope.

Using AtomScope

• Isolation: Creating multiple AtomScope blocks ensures that Scoped atoms inside them do not share state with each other.
• Observation: Use .scopedObserve { snapshot in ... } on an AtomScope to monitor changes to atoms within that specific scope.
• Custom Scopes: You can define a scopeID on a Scoped atom to find a matching scope in a nested hierarchy, allowing for controlled sharing across specific boundaries.

// Isolated atoms via Scoped attribute
struct TextInputAtom: StateAtom, Scoped, Hashable {
    func defaultValue(context: Context) -> String { "" }
}

VStack {
    // These two views will NOT share TextInputAtom state
    AtomScope {
        TextInputView()
    }

    AtomScope {
        TextInputView()
    }
}

// Sharing via custom scope ID
struct TextScopeID: Hashable {}

struct TextInputAtom: StateAtom, Scoped, Hashable {
    var scopeID: TextScopeID { TextScopeID() }
    func defaultValue(context: Context) -> String { "" }
}

AtomScope(id: TextScopeID()) {
    TextInputView()
}

AtomScope {
    // Shares state with the TextInputView in the parent scope
    TextInputView()
}

Modifiers can be applied to any atom to create a derived version of that atom. This is useful for performance optimization (reducing view re-computations) or tracking specific state changes.

Available Modifiers:

• .previous: Provides the previous value of the atom instead of the current one. Useful for comparing changes.
• .latest(_:): Provides the most recent value that matches a specific condition (using a KeyPath).
• .changes(of:): Derives a partial property using a KeyPath. The view will only re-compute if the specific property changes and is Equatable compliant. This is a key performance optimization tool.

// Example: Using .previous and .latest
struct CounterView: View {
    @WatchState(CounterAtom())
    var currentValue

    @Watch(CounterAtom().previous)
    var previousValue

    @Watch(ItemAtom().latest(\.isValid))
    var latestValidItem

    var body: some View {
        VStack {
            Text("Current: \(currentValue)")
            Text("Previous: \(previousValue ?? 0)")
        }
    }
}

// Example: Using .changes(of:) for performance
struct CountDisplayView: View {
    @Watch(CountAtom().changes(of: \.description))
    var description

    var body: some View {
        Text(description)
    }
}

The AtomEffect API allows you to synchronize side effects (like logging, persistence, or timers) with an atom's lifecycle. Effects are attached to atoms using the effect(context:) method.

Predefined Effects

• InitializingEffect: Runs before the atom is initialized.
• InitializeEffect: Runs after the atom is initialized.
• UpdateEffect: Runs whenever the atom's value is updated.
• ReleaseEffect: Runs when the atom is no longer used and is released.

Custom Effects

You can implement the AtomEffect protocol to manage stateful side effects. The effect is retained as long as the atom is in use.

Example of a custom effect managing a timer:

struct CounterAtom: StateAtom, Hashable {
    func defaultValue(context: Context) -> Int { 0 }

    func effect(context: CurrentContext) -> some AtomEffect {
        CountTimerEffect()
    }
}

final class CountTimerEffect: AtomEffect {
    private var timer: Timer?

    func initialized(context: Context) {
        timer = Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { _ in
            context[CounterAtom()] += 1
        }
    }

    func updated(context: Context) {
        print("Count: \(context.read(CounterAtom()))")
    }

    func released(context: Context) {
        timer?.invalidate()
        timer = nil
    }
}

The library manages state using an internal Directed Acyclic Graph (DAG). You can inspect this graph using two methods:

1. On-demand via @ViewContext: Use context.snapshot() to capture the current state and snapshot.graphDescription() to get a string representation.
2. Continuous observation: Use the .observe { ... } modifier on AtomRoot (for app-wide changes) or .scopedObserve { ... } on AtomScope (for scoped changes) to receive snapshots whenever state changes.

Captured snapshots can be converted to DOT format for visualization with Graphviz, or used for time travel debugging by calling context.restore(snapshot) to revert the dependency graph and atom values to a previous state.

@ViewContext
var context

var debugButton: some View {
    Button("Dump dependency graph") {
        let snapshot = context.snapshot()
        print(snapshot.graphDescription())
    }
}

// Or continuous observation
AtomRoot {
    HomeScreen()
}
.observe { snapshot in
    print(snapshot.graphDescription())
}