Boutique 3.0 Beta 1: An Observable Girl, Living In An Observable World

[mergesort]

Boutique 3.0 is the biggest update to Boutique since the release of Boutique 2.0, just over two years ago. Boutique 3.0 isn't a complete rewrite — I love how Boutique works and the last thing I want to do is change everything about it. But I want to continue advancing what Boutique can do, so Boutique has been modernized with rewritten internals to make it even better, simpler, and more flexible.

I want to emphasize, the Boutique you know and love is not changing — it's being extended to become even better, and here's how.

---

1. Goodbye ObservableObject, hello @Observable. You can now use Boutique's Store, @StoredValue, and @SecurelyStoredValue with @Observable. This makes your code cleaner, faster, and simpler to reason about. Boutique 3.0 is even easier to integrate into an app, without any additional concepts to learn.

2. Swift 6 support. Swift 6 is a big change, and you can continue using Boutique in Swift 5 projects — no rush to upgrade. The Swift 6 data race safety upgrades have helped me track down some rare race conditions that may have occurred. Boutique's Store, @StoredValue, and @SecurelyStoredValue are now bound to @mainactor, to prevent loss or inconsistency of data.

3. New APIs, for now and later. By cleaning up Boutique's internals, I've laid the groundwork for new features that will help Boutique match all that SwiftData has to offer. It's always been a goal for Boutique to be perfect out of the box for 95% of projects, but my goal now is to get Boutique to 99% — making it a fit for almost every project.

---

Here is a list of important high level changes, eschewing details buried in the code.

Store & @Stored

• Boutique no longer depends on Combine, and values are now published through AsyncStream. This makes observing the Store's items cleaner, and you can now observe changes through onChange rather than onReceive.

// Before
.onReceive(richNotesController.$notes.$items, perform: {
    self.notes = $0
})

// After
.onChange(of: self.richNotesController.notes, initial: true, { _, newValue in
    self.notes = newValue
})

// Note: The `initial` property being set to true is not required, but it is important for reproducing the previous behavior where `$items` would be called in `onReceive` where the Store was empty.

• A new events property publishes StoreEvent values, allowing you to observe individual changes when a Store is initialized, loaded, and when insert and remove operations occur.

func monitorNotesStoreEvents() async {
    for await event in self.richNotesController.$notes.events {
        switch event.operation {

        case .initialized:
            print("[Store Event: initialized] Our Notes Store has initialized")

        case .loaded:
            print("[Store Event: loaded] Our Notes Store has loaded with notes", event.items)

        case .insert:
            print("[Store Event: insert] Our Notes Store inserted notes", event.items)

        case .remove:
            print("[Store Event: remove] Our Notes Store removed notes", event.items)
        }
    }
}

@StoredValue & @SecurelyStoredValue

• By implementing Observation tracking, you can now create a Store, StoredValue, or SecurelyStoredValue inside of an @Observable type. Please note that you will have to add @ObservationIgnored to your properties, but don't worry, they will still be observed properly.

@Observable
final class AppState {
    @ObservationIgnored
    @StoredValue(key: "isRedPandaModeEnabled")
    var isRedPandaModeEnabled = false

    @ObservationIgnored
    @SecurelyStoredValue(key: "redPandaData")
    var redPandaData: RedPandaData?
}

• Due to ObservableObject restrictions, we previously could not break down an ObservableObject into smaller objects while still observing their changes. Thanks to @Observable, we can now enforce a cleaner separation of concerns by splitting up large objects into smaller ones.

// Before
@MainActor
@Observable
final class Preferences {
    @ObservationIgnored
    @StoredValue(key: "hasSoundEffectsEnabled", storage: Preferences.store)
    public var hasSoundEffectsEnabled = false

    @ObservationIgnored
    @StoredValue(key: "hasHapticsEnabled", storage: Preferences.store)
    public var hasHapticsEnabled = true

    @ObservationIgnored
    @StoredValue(key: "likesRedPandas", storage: Preferences.store)
    public var likesRedPandas = true
}

// After
@Observable
final class Preferences {
    var userExperiencePreferences = UserExperiencePreferences()
    var redPandaPreferences = RedPandaPreferences()
}

@MainActor
@Observable
final class UserExperiencePreferences {
    @ObservationIgnored
    @StoredValue(key: "hasSoundEffectsEnabled")
    public var hasSoundEffectsEnabled = false

    @ObservationIgnored
    @StoredValue(key: "hasHapticsEnabled")
    public var hasHapticsEnabled = true
}

@MainActor
@Observable
final class RedPandaPreferences {
    @ObservationIgnored
    @StoredValue(key: "isRedPandaFan")
    public var isRedPandaFan = true
}

• You can now use StoredValue and SecurelyStoredValue without a property wrapper, thanks to new initializers. This makes them usable in any object, not just one that has the @Observable macro.

// StoredValue.swift
// NEW
public convenience init(key: String, default defaultValue: Item, storage userDefaults: UserDefaults = UserDefaults.standard)

// SecurelyStoredValue.swift
// SAME AS BEFORE
public init(key: String, service: KeychainService? = nil, group: KeychainGroup? = nil)

Notes & Deprecations

• Boutique's minimum deployment target is now iOS 17/macOS 14, the first versions of iOS and macOS that support @Observable.
• AsyncStoreValue has been deprecated, as it was not widely used after its initial introduction.
• The store.add function is now fully deprecated. Any code calling store.add should instead call store.insert.
• By removing the dependency on Combine, Boutique can explore adding Linux support, but it is not officially supported yet.

Todo

Before Boutique 3.0 is officially released, I still need to:

• Update all documentation to reflect the change from ObservableObject to @Observable.
• Ensure all tests pass (Boutique's tests have been rewritten with the new Swift Testing framework and currently pass, but only when run with the new .serialized trait.)
• Integrate Boutique 3.0 into existing projects to ensure it works as expected with equal or better performance than Boutique 2.0.

---

I welcome any feedback or suggestions for Boutique 3.0, especially if you integrate Boutique into one of your projects and find ways to improve it! ❤️

---

This discussion was created from the release Boutique 3.0 Beta 1: An Observable Girl, Living In An Observable World.

[joeycarmello]

Love it! Giving main a try in one of my swift 6 projects and so far smooth sailing.

The main use case I'm having trouble fitting into the current API is around document storage. (Maybe I should be using Bodega directly?)
For example:
1: Given a @Store I'd like to lookup a single entity by its id.
2: Or perhaps more generally, a top-level Stored dictionary type. Does it make sense to use @Storedvalue with a dictionary that may grow large?

[mergesort]

Thank you, glad to hear it's working well for you! Please don't be shy if you have any feedback. 🙂

For binary data (files, images, etc), I would recommend using Bodega directly. Boutique takes all of the items you've persisted and loads them into memory when initializing the Store, so if you have a large amount of data, you will be loading a lot of data into memory.

While it's possible to fit this into the shape of @StoredValue this way, but given that data will be stored in memory and UserDefaults, I think this could be even less performant than the Store option.

---

For what it's worth I follow this pattern myself in my apps, and I know someone else who just integrated Bodega into her app to store dozens of CSV files in a more ergonomic format, so this is a considered to be a very reasonable use case for Bodega. I have some documentation for how you could build a system like this, where images can be any type of file.

[joeycarmello]

I think I used "document" a little too loosely. What I really want is an index of my model objects. This comes up all the time whenever I have two related types with separate stores. For example, say there's a Store of Messages and another Store of Authors where each message has an author id. During rendering I'd like to lookup the author for a message without looping over all authors. Or a different configuration where there's a Store of Threads and a Store of Messages, and I only want to lookup messages for the currently viewing thread.

Thanks, I hadn't seen that Bodega example and it's super useful for my thinking here. Will give Bodega a shot, a custom store might be what I need, though it's a shame it doesn't have any observability out of the box. Maybe what I should really be doing is observing the Boutique Store and transform the data how I need it.

[mergesort]

This is actually a feature that I thought I'd created an issue for, but it turns out I haven't. I've wanted this for a very long time similar to SwiftData's relationships but a different flavor.

What I plan on doing (and will write up an issue for) is allow users to define change handlers on a Store, with relationships to another Store. Rather than SwiftData's @Relationship macro, this would instead be defined on the Store level, that way you do not have to modify your models to know anything about how they're being Stored.

Similar to what you mention, this would remove a lot of code that I have in my apps where I loop over the contents of another Store. It would also stay true to Boutique's philosophy of you not needing to change the way you build apps to get offline support for free. I'd love to know if that's what you were thinking @joeycarmello, and if the idea resonates with you!

[joeycarmello]

One bug I'm encountering is that my app appears to be reading stale cache data on app launch (in the simulator at least). Entries I've explicitly deleted such as via try await self.$threads.removeAll().insert(threads).run() do not appear to be persisted by the next time I run the app.

[mergesort]

I apologize for the delayed reply, I was trying to figure out #70 in between a lot of work and some health issues. I believe that fix should fix your issue, and I've merged it into the 3.0 branch. Could you let me know if this fixes your problem @joeycarmello?