playbooks

home / skills / nonameplum / agent-skills / swift-sharing

swift-sharing skill

/swift-sharing

This skill helps you share and persist app state across components with observable changes and safe mutation.

npx playbooks add skill nonameplum/agent-skills --skill swift-sharing

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

Files (21)
SKILL.md
2.4 KB
---
name: swift-sharing
description: A library for sharing state across your app with persistence and observation support
---

# Sharing

Instantly share state among your app's features and external persistence layers, including user

## Documentation Structure

### Essentials

- **Persistence strategies** ([Articles/PersistenceStrategies.md](Articles/PersistenceStrategies.md)): Learn about the various persistence strategies that ship with the library, as well as how to create
- **Mutating shared state** ([Articles/MutatingSharedState.md](Articles/MutatingSharedState.md)): Learn how to mutate shared state in a safe manner in order to prevent race conditions and data loss.
- **Observing changes to shared state** ([Articles/ObservingChanges.md](Articles/ObservingChanges.md)): Learn how to observe changes to shared state in order to update your UI or react to changes.
- **Dynamic Keys** ([Articles/DynamicKeys.md](Articles/DynamicKeys.md)): Learn how to dynamically change the key that powers your shared state.
- **Deriving shared state** ([Articles/DerivingSharedState.md](Articles/DerivingSharedState.md)): Learn how to derive shared state to sub-parts of a larger piece of shared state.
- **Reusable, type-safe keys** ([Articles/TypeSafeKeys.md](Articles/TypeSafeKeys.md)): Learn how to define keys for your shared state that allow you to reference your data in a statically
- **Initialization rules** ([Articles/InitializationRules.md](Articles/InitializationRules.md)): Learn the various ways to initialize shared state, both when using a persistence strategy and
- **Testing** ([Articles/Testing.md](Articles/Testing.md)): Learn how to test features that use shared state, even when persistence strategies are involved.
- **Gotchas of @Shared** ([Articles/Gotchas.md](Articles/Gotchas.md)): Learn about a few gotchas to be aware of when using shared state in your application.

### Persistence


### Custom persistence


### Migration guides

- **Migration guides** ([Articles/MigrationGuides.md](Articles/MigrationGuides.md)): Learn how to upgrade your application to the newest version of Sharing.

## Usage Notes

- Documentation is organized progressively from getting started to advanced topics
- Start with the Introduction or Getting Started section
- Consult specific guides for detailed information

## License & Attribution

This skill contains content converted from DocC documentation format.

Overview

This skill describes swift-sharing, a Swift library for sharing state across your app with built-in persistence and observation support. It explains core concepts, persistence strategies, safe mutation patterns, dynamic keys, derived state, and testing guidance. The content is organized progressively from basics to advanced topics so you can integrate sharing incrementally.

How this skill works

The library exposes a shared state abstraction keyed by type-safe keys that can be observed and mutated safely to avoid races and data loss. Persistence strategies are pluggable: you can use built-in strategies or implement custom storage backends. The skill covers dynamic key replacement, deriving sub-state from larger pieces, and rules for initializing state when persistence is involved.

When to use it

  • You need a single source of truth accessible from multiple features or modules.
  • You want automatic observation to update UI or trigger side effects on state changes.
  • You must persist shared state across launches with configurable storage strategies.
  • You want type-safe keys and compile-time guarantees when referencing shared values.
  • You need to test features that rely on shared state and simulate persistence.

Best practices

  • Define reusable, type-safe keys to avoid string-based errors and clarify intent.
  • Follow the mutating guidelines to perform safe, atomic updates and prevent race conditions.
  • Use derived state to expose only the sub-parts features need, minimizing coupling.
  • Choose or implement a persistence strategy that matches your consistency and performance needs.
  • Write tests that inject test persistence strategies so you can verify behavior deterministically.

Example use cases

  • Share user preferences and persist them to disk so multiple screens reflect changes immediately.
  • Maintain a global session object that is observed by authentication and navigation features.
  • Derive a filtered list state from a larger dataset to present in a child view while keeping the source canonical.
  • Swap persistence backends for testing or migrate storage formats using the provided migration guidance.
  • Dynamically change the key powering a piece of shared state to support multi-tenant or user-scoped data.

FAQ

How do I avoid race conditions when mutating shared state?

Use the library's provided mutation APIs that perform atomic updates and follow the documented mutating patterns to coordinate concurrent access.

Can I use a custom storage backend for persistence?

Yes. The skill documents built-in persistence strategies and explains how to implement custom persistence strategies to fit your storage requirements.