Version 1.0 Roadmap

[MaximBazarov]

Putting a draft of the API I envision as a version 1.

State definition

To define the state that is managed by SharedEnvironment user neds to apply the EnvironmentObservable root class of the states and then each variable that have a default value. Will be wrapped with required wrappers to enable observability.

e.g.

@EnvironmentObservable
final class Notes {
    
    @RemoteValue(.myBackend(.nameRequest))
    @Persistent(.secureStorage("com.myapp.ios.note.name"))
    var name: String = ""
    
    var count: Int = 0

    var comp = Computed<Int> {
        $0[\SomeRoot.someValue] + $0[\SomeRoot.someOtherValue]
    }

    var comp = InitialValueComputed<Int> {
        $0[\SomeRoot.someValue] + $0[\SomeRoot.someOtherValue]
    }
}

Computed and InitialValueComputed are the specicial type of states that has custom calculation using environment.

Value Access

to access the value we need macros @Bind and @Observe that take the \Root.observableValue KeyPath and expand to a property wrapper that are derived from the type of the value and the root.

@Bind(\Notes.name) var notesName

those macros provide updates to SwiftUI views to cause the rendering. For non SwiftUI objects we need to wrap the object in @EnvironmentalObject to have a method onUpdate which environment will call when any of @Bind values change.

@EnvironmentalObject final class MyService {
    @Bind(\Notes.name) var name

    func onUpdate() {
        print(name)
    }

Roadmap

1. State Definition
   1.1. Atomic Root -> root class for atomic values.
   1.2. RootGroup -> a group of atomic roots that environment provides based on ID
   1.3. Simple state -> stores the value and provides observability
   1.4. Computed state -> computes it's value form environment, invalidated when states used are updated.
   1.6. DefaultComputed state -> same as computed but only computes once when initial value is needed.
   1.7. GroupedComputed State -> same as computed but takes group id as an additional parameter
   1.8. Grouped DefaultComputed State

2. State Access
   2.1. SwiftUI
   2.2. Non SwiftUI

3. State management
   3.1. Decision - sync state update.
   3.2. Effect - async operation that produces decisions.

4. Testing
   2.1. SwiftUI
   2.2. Non SwiftUI

5. Macros - user must write only what is absolutely necessary.

6. Persistency - the way to define a strategy, that has access to environment and provided with a key to persist value across sessions.

// stretch
7. Remote Value - the way to define a strategy, that has access to environment and provides the synchronisation. Might require a special type of states that are async.

All this is open to discussion, please share your opinions, and more importantly questions, and suggestions what needs to be included in the roadmap so everyone understands what needs to be done and ready to contribute.

[MaximBazarov]

cc @ipedro @serjooo @Garfeild

[serjooo]

Hey Maxim, great job drafting a potential version 1 roadmap! Looks great!

I really like the direction of using Swift Macros to remove the boilerplate/learning curve from the developer on how to implement their state objects correctly. From what I understand in the current version, we have implementations of @Bind, @ObservableValue, etc as PropertyWrappers. What would be the benefit of having them as Macros as suggested? I also am trying to keep in mind that currently Macros come with a compile time cost. There seems to be issues in the initial version shipped. I definitely expect it to be fixed in upcoming Swift versions, but they will have some overhead cost. Therefore, the main question I think we should answer is, where do we draw the line between using Swift Macro versus using a PropertyWrapper?

Another feedback that I have is around the naming of @EnvironmentObject and @EnvironmentalObject. The first one is pretty clear and straightforward; however, the latter seems to be very close and confusing. We mentioned that we would want to use the latter for non-SwiftUI cases where we would get a callback on the onUpdate function. Maybe we can name them more explicitly so they're understandable when to use which from the name. Maybe something along the lines of @ObservedEnvironmentObject / @AutomatedEnvironmentObject and @CallbackEnvironmentObject / @ManualEnvironmentObject. I know they aren't perfect names yet, but just to get the thought train going on maybe finding a better name that's easier to follow and use.

Let's now talk about the different StateDefinitions. I can see we have almost a permutation of StateDefinitions based if it is Grouped or not. I'm wondering if we can decrease them by a better API design, where developer can use the same StateDefinition and optionally opt-in for IDs if they want, and if not it is fine and we get the default behavior. In this case, let's imagine we only have AtomicRoot, and then I can optionally use a group of IDs if needed, and if not the AtomicRoot works as it does now. We can leave the implementation details internal and keep the API surface easy and digestible. What do you think?

These are my thoughts so far, I'll think about the rest as we go. Thank you for kicking off this discussion!

[MaximBazarov]

Hey @serjooo, thank you for the excellent points!

1. Regarding macros, I agree they are not ready yet. It was a fun experiment, but for Decide, at least for now, it goes against the core principle of keeping it simple in terms of user experience. As an experiment, we might consider having a separate framework, for example, Macrocide, that imports Decide and provides macros.

2. Yes naming is a weak point here. I would suggest shaping the functionality first and having a comprehensive naming discussion once we have all the components designed for Version 1.0. right now many components will stop existing. (Will appreciate if you can drive this discussion already creating some names for the components like Environment, Binds etc, that are public API.)

3. Again, an excellent point. While implementing the Decision Environment, I realized it wasn't scaling well. I had to add support for each modifier, and since there are expected to be plenty of them, I came up with a solution. I will create a separate thread to discuss this in detail. Here's a brief glimpse:

In short, there is a Storage protocol and RW and RO storage protocols to distinguish storages. For example, Computation is a read-only storage, whereas the raw value is a read/write one. This way, the Decision Environment would only support anything that points to storage and provide set-only for RW storages.

I have a couple of playgrounds in mind and will share them soon.