OpenParable
Skip to content
← Back to skills

Boutique Stored Values

Development
boutique-stored-values

Boutique Stored Values is an Agent Skill for development published in the mergesort/Boutique repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Persist individual values with Boutique's @StoredValue (UserDefaults) and @SecurelyStoredValue (Keychain), including set, reset, toggle, bindings, keypath setters, array and dictionary helpers, and async observation. Use when storing preferences, settings, feature flags, or sensitive data like auth tokens.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/mergesort/Boutique/blob/HEAD/plugins/boutique/skills/boutique-stored-values/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/boutique-stored-values, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Boutique Stored Values

Use this skill when you need to persist individual values (preferences, settings, feature flags) using @StoredValue (backed by UserDefaults) or sensitive data (auth tokens, passwords) using @SecurelyStoredValue (backed by the system Keychain).

Prerequisites

  • Boutique added as a dependency via Swift Package Manager.
  • Stored values must conform to Codable, Sendable, and Equatable.

@StoredValue (UserDefaults)

Basic declaration

@StoredValue(key: "hasHapticsEnabled")
var hasHapticsEnabled = false

@StoredValue(key: "lastOpenedDate")
var lastOpenedDate: Date? = nil

@StoredValue(key: "currentTheme")
var currentlySelectedTheme: Theme = .light

In @Observable classes

Always pair with @ObservationIgnored to prevent duplicate observation tracking.

@Observable
final class Preferences {
    @ObservationIgnored
    @StoredValue(key: "hasHapticsEnabled")
    var hasHapticsEnabled = false

    @ObservationIgnored
    @StoredValue(key: "lastOpenedDate")
    var lastOpenedDate: Date? = nil

    @ObservationIgnored
    @StoredValue(key: "currentTheme")
    var currentlySelectedTheme: Theme = .light
}

Setting and resetting values

Use the $ projected value to access set and reset.

// Set a new value
$lastOpenedDate.set(.now)
$currentlySelectedTheme.set(.dark)

// Reset to the default value provided at declaration
$lastOpenedDate.reset()          // Back to nil
$currentlySelectedTheme.reset()  // Back to .light

Boolean toggle

$hasHapticsEnabled.toggle()

// Equivalent to:
// $hasHapticsEnabled.set(!hasHapticsEnabled)

Keypath setter (nested property updates)

Update a single property inside a complex stored object without manually copying.

struct UserPreferences: Codable, Sendable, Equatable {
    var hasHapticsEnabled: Bool
    var prefersDarkMode: Bool
    var prefersWideScreen: Bool
}

@ObservationIgnored
@StoredValue(key: "userPreferences")
var preferences = UserPreferences(
    hasHapticsEnabled: true,
    prefersDarkMode: false,
    prefersWideScreen: false
)

// Update a single nested property
$preferences.set(\.prefersDarkMode, to: true)

Array helpers

When a @StoredValue holds an array, convenience methods are available.

@ObservationIgnored
@StoredValue(key: "favoriteTags")
var favoriteTags: [String] = []

// Append an element
$favoriteTags.append("swift")

// Toggle presence (add if missing, remove if present)
$favoriteTags.togglePresence("swift")

// Replace an element
$favoriteTags.replace("swfit", with: "swift")

Dictionary helpers

@ObservationIgnored
@StoredValue(key: "featureFlags")
var featureFlags: [String: Bool] = [:]

// Update a key
$featureFlags.update(key: "darkMode", value: true)

// Remove a key by setting nil
$featureFlags.update(key: "darkMode", value: nil)

Async observation

Observe changes over time with the values AsyncStream.

func monitorThemeChanges() async {
    for await theme in preferences.$currentlySelectedTheme.values {
        print("Theme changed to", theme)
    }
}

Custom UserDefaults

@StoredValue(key: "sharedSetting", storage: UserDefaults(suiteName: "group.com.example.app")!)
var sharedSetting = false

Direct initialization (without property wrapper syntax)

Useful in contexts where property wrappers are not supported.

let hasHapticsEnabled = StoredValue(key: "hasHapticsEnabled", default: false)

@SecurelyStoredValue (Keychain)

Key differences from @StoredValue

Aspect@StoredValue@SecurelyStoredValue
Backing storeUserDefaultsSystem Keychain
Default valueRequiredNot supported
wrappedValue typeItemItem? (always optional)
Mutation methodsset(_:), reset()set(_:) throws, remove() throws
Use casePreferences, settingsPasswords, tokens, secrets

Declaration

Do not make the type optional yourself, the wrapper handles that. Declaring @SecurelyStoredValue<String?> creates a double optional.

@Observable
final class SecurityManager {
    @ObservationIgnored
    @SecurelyStoredValue<String>(key: "authToken")
    var authToken

    @ObservationIgnored
    @SecurelyStoredValue<String>(key: "refreshToken")
    var refreshToken
}

Setting and removing values

// Set a value (throws on keychain errors)
try $authToken.set("eyJhbGciOiJIUzI1NiIs...")

// Remove from keychain
try $authToken.remove()

// Set to nil (same as remove)
try $authToken.set(nil)

Keychain service and group

@SecurelyStoredValue<String>(
    key: "authToken",
    service: KeychainService(value: "com.example.auth"),
    group: KeychainGroup(value: "group.com.example.shared")
)
var authToken

Boolean toggle (throws)

@ObservationIgnored
@SecurelyStoredValue<Bool>(key: "biometricsEnabled")
var biometricsEnabled

try $biometricsEnabled.toggle()

Array and dictionary helpers (throws)

@ObservationIgnored
@SecurelyStoredValue<[String]>(key: "trustedDevices")
var trustedDevices

try $trustedDevices.append("device-abc-123")
try $trustedDevices.replace("device-old", with: "device-new")

Keypath setter (throws)

try $credentials.set(\.accessToken, to: "new-token")

Async observation

func monitorAuthState() async {
    for await token in securityManager.$authToken.values {
        if let token {
            print("Authenticated")
        } else {
            print("Logged out")
        }
    }
}

Structuring Preferences

For apps with many preferences, break them into focused @Observable classes.

@Observable
final class Preferences {
    var userExperience = UserExperiencePreferences()
    var notifications = NotificationPreferences()
}

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

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

@Observable
final class NotificationPreferences {
    @ObservationIgnored
    @StoredValue(key: "pushEnabled")
    var pushEnabled = true

    @ObservationIgnored
    @StoredValue(key: "emailDigestEnabled")
    var emailDigestEnabled = false
}

Common Mistakes

  • Forgetting $: Use $storedValue.set(value), not storedValue.set(value). The wrappedValue is the raw value; the projectedValue (via $) is the StoredValue with mutation methods.
  • Missing @ObservationIgnored: Always add @ObservationIgnored before @StoredValue or @SecurelyStoredValue in @Observable classes.
  • Double optional: Don't write @SecurelyStoredValue<String?>. The wrapper already makes wrappedValue optional.

Notes

  • @StoredValue and @SecurelyStoredValue are both @MainActor isolated.
  • Values from @StoredValue are available synchronously on app launch.
  • Values from @SecurelyStoredValue are read from the Keychain synchronously.
  • See boutique-swiftui skill for using .binding with SwiftUI controls.