Boutique Documentation

Boutique is a persistence library designed for SwiftUI, UIKit, and AppKit applications. It uses a dual-layered memory + disk caching architecture to provide real-time updates and full offline storage.

Key characteristics include:

• Automatic Persistence: Data saved to a Store is automatically persisted to disk.
• Real-time Updates: State changes propagate to all views automatically.
• Simple API: Data is exposed as regular Swift arrays or values, minimizing the need for complex database logic.
• Architecture Agnostic: While it promotes a Model-View-Controller-Store pattern, it can be integrated into any existing architecture.

Boutique's functionality centers around two primary abstractions:

1. Store: When you save data to a Store, it is automatically persisted. The data is exposed to your application as a regular Swift array.
2. Property Wrappers:
   • @StoredValue: Used to save and retrieve a singular Swift value. You update it using $storedValue.set(value).
   • @SecurelyStoredValue: Works identically to @StoredValue but is intended for sensitive data requiring secure storage.

Unlike Redux or The Composable Architecture, Boutique does not require defining Actions or Reducers; persistence is handled automatically.

The @Stored property wrapper allows you to link a single property to a Store. This creates an in-memory and on-disk cache for that value. It is highly useful for sharing state across multiple views in SwiftUI, UIKit, or AppKit. Because @Stored is @Observable, views can react to changes automatically.

extension Store where Item == Note {
    static let notesStore = Store<Note>(
        storage: SQLiteStorageEngine.default(appendingPath: "Notes")
    )
}

@Observable
final class NotesController {
    /// Automatically handles in-memory and on-disk caching
    @Stored(in: .notesStore) var notes

    func saveNote(note: Note) async throws {
        try await self.$notes.insert(note)
    }
}

All items stored in Boutique must conform to StorableItem, which requires Codable & Sendable.

• Structs (Preferred): Structs receive Sendable conformance automatically if all their stored properties are Sendable.
• Enums: Enums can be used as stored items if they conform to Codable, Sendable, and Equatable.

struct Note: Codable, Sendable, Identifiable, Equatable {
    let id: String
    let text: String
    let createdAt: Date
}

enum Theme: String, Codable, Sendable, Equatable {
    case light
    case dark
    case system
}

While Boutique can store binary data like images, it is not recommended for large binary blobs. Storing images in Boutique can cause significant memory ballooning.

For storing images or other large binary data to disk, use Bodega instead. Boutique is optimized for handling thousands of small objects rather than large binary files.

The Store, StoredValue, and SecurelyStoredValue are annotated with @MainActor.

What this means:

• Synchronous access to the Store is safe and intended for the main thread.
• It does not force heavy asynchronous work (like disk I/O or network requests) onto the main thread.
• The underlying Bodega framework performs all heavy lifting (persistence/loading) asynchronously on background threads.

Best Practice: Avoid performing heavy synchronous computations inside a @MainActor scope, as that will block the main thread. Boutique's internal work is designed to be lightweight and offload heavy tasks to background threads automatically.

Boutique provides a family of property wrappers designed to work with regular Swift values and arrays while handling automatic data persistence. This allows you to build offline-first, state-driven SwiftUI applications without managing a database manually.

Key property wrappers include:

• @Stored
• @StoredValue
• @SecurelyStoredValue

When building applications with Boutique, follow these architectural patterns:

1. One controller per domain: Create focused @Observable controllers per data domain (e.g., NotesController, PhotosController) rather than one monolithic controller.
2. Store as implementation detail: Expose domain-specific methods (like addNote or removeNote) on your controllers. Do not expose the Store directly to your SwiftUI views.
3. API-first, store-second: Perform API calls first, then sync the results to the local store upon success. This ensures the local store acts as a reliable cache of the server's state.
4. Preferences as separate classes: If you have large preference objects, break them into smaller @Observable classes grouped by specific feature areas.

Because Boutique integrates with Swift's @Observable macro, you can break down large, monolithic state objects into smaller, focused, and reactive sub-objects. This allows you to maintain reactivity across a hierarchy of models while keeping individual components maintainable.

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

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