playbooks

home / skills / willsigmon / sigstack / preferences-store-expert

preferences-store-expert skill

/plugins/app-dev/skills/preferences-store-expert

This skill helps manage user preferences with SwiftData persistence and async observations, providing a single source of truth through load, update, and

npx playbooks add skill willsigmon/sigstack --skill preferences-store-expert

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
710 B
---
name: Preferences Store Expert
description: Work with Leavn PreferencesStore - SwiftData persistence, snapshot patterns, async observation, entity relationships, migration from UserDefaults
allowed-tools: Read, Edit, Grep
---

# Preferences Store Expert

Expert in PreferencesStore architecture:

**Pattern**:
- Entities in SwiftData
- Snapshots (Sendable, Codable)
- Async observation
- Single source of truth

**Key files**:
- PreferencesStore.swift
- PreferenceModels.swift
- PreferencesStore+{Domain}.swift extensions

**Operations**:
- `loadX()` → snapshot
- `updateX { }` → mutation
- `observeSnapshots()` → AsyncStream

Use when: Preferences issues, settings persistence, SwiftData, user data

Overview

This skill provides deep expertise working with a PreferencesStore built on SwiftData, focusing on a single-source-of-truth preferences architecture. It covers entity modeling, Sendable/Codable snapshot patterns, async observation, and migration strategies from UserDefaults. The goal is reliable, testable, and concurrency-safe user settings persistence.

How this skill works

The store persists domain-specific preference entities in SwiftData and exposes immutable snapshots that are Sendable and Codable for safe cross-thread use. It offers loadX() methods to produce current snapshots, updateX { } mutation blocks for coordinated writes, and observeSnapshots() that returns an AsyncStream of snapshots for reactive UI/logic. Extensions split domain concerns into PreferencesStore+{Domain}.swift for clean separation and testability.

When to use it

  • Replacing or migrating existing UserDefaults-based settings to SwiftData for richer relationships and type safety.
  • Implementing a single source of truth for app settings shared across threads and processes.
  • Needing reactive updates in SwiftUI or async code via AsyncStream snapshots.
  • Handling complex preference entities with relationships or versioned schemas.
  • Ensuring Sendable, Codable snapshots for background tasks and concurrency-safe flows.

Best practices

  • Model preference records as SwiftData entities but expose immutable snapshots to callers.
  • Keep mutation surface small: use updateX { } blocks that validate and mutate within one transaction.
  • Use Codable + Sendable snapshots to move state across concurrency domains safely.
  • Organize code into domain extensions (PreferencesStore+{Domain}) to reduce coupling.
  • Provide explicit migration paths from UserDefaults: map keys to entities and run idempotent transforms.

Example use cases

  • Migrating onboarding flags, feature toggles, and user settings from UserDefaults into SwiftData entities.
  • Driving SwiftUI views with observeSnapshots() AsyncStream to update UI when preferences change.
  • Performing bulk preference updates inside updateX { } to ensure atomicity and consistency.
  • Serializing snapshots for logging, backups, or sending sanitized settings to analytics.
  • Modeling user-specific settings that reference other entities (e.g., default workspace or theme object).

FAQ

How do snapshots help with concurrency?

Snapshots are immutable, Sendable, and Codable so they can be safely sent across threads and used in async contexts without risking data races.

When should I migrate from UserDefaults?

Migrate when preferences require relationships, stronger typing, versioned schemas, or when you need transactional updates and async observation.