Add PersistentKeyValues AsyncSequence observation

Author: kylehughes

.github/workflows/deploy_documentation.yml

@@ -23,12 +23,14 @@ jobs:
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: macos-15
+    runs-on: macos-26
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+      - name: Select Xcode
+        run: sudo xcode-select -s /Applications/Xcode_26.4.app
       - name: Set Up GitHub Pages
-        uses: actions/configure-pages@v3
+        uses: actions/configure-pages@v5
       - name: Build Documentation
         run: |
           xcodebuild docbuild \
@@ -44,7 +46,7 @@ jobs:
         run: |
           echo "<script>window.location.href += \"/documentation/persistentkeyvaluekit\"</script>" > _site/index.html;
       - name: Upload Documentation Artifact to GitHub Pages
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v3
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4

.github/workflows/test.yml

@@ -16,8 +16,8 @@ jobs:
     strategy:
       matrix:
         include:
-          - os: macos-15
-            xcode: '16.0'
+          - os: macos-26
+            xcode: '26.4'
     name: Get Environment Details (Xcode ${{ matrix.xcode }})
     runs-on: ${{ matrix.os }}
     steps:
@@ -37,34 +37,34 @@ jobs:
     strategy:
       matrix:
         include:
-          - os: macos-15
-            xcode: '16.0'
+          - os: macos-26
+            xcode: '26.4'
             platform: iOS
-            destination: "name=iPhone 16 Pro"
+            destination: "name=iPhone 17 Pro"
             sdk: iphonesimulator
-          - os: macos-15
-            xcode: '16.0'
+          - os: macos-26
+            xcode: '26.4'
             platform: tvOS
             destination: "name=Apple TV 4K (3rd generation)"
             sdk: appletvsimulator
-          - os: macos-15
-            xcode: '16.0'
+          - os: macos-26
+            xcode: '26.4'
             platform: visionOS
             destination: "name=Apple Vision Pro"
             sdk: xrsimulator
-          - os: macos-15
-            xcode: '16.0'
+          - os: macos-26
+            xcode: '26.4'
             platform: watchOS
-            destination: "name=Apple Watch Ultra 2 (49mm)"
+            destination: "name=Apple Watch Ultra 3 (49mm)"
             sdk: watchsimulator
-          - os: macos-15
-            xcode: '16.0'
+          - os: macos-26
+            xcode: '26.4'
             platform: macOS
     name: Test ${{ matrix.platform }} (Xcode ${{ matrix.xcode }})
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout project
-        uses: actions/checkout@master
+        uses: actions/checkout@v4
 
       - name: Select Xcode
         run: sudo xcode-select -s /Applications/Xcode_${{ matrix.xcode }}.app
@@ -77,4 +77,4 @@ jobs:
 
       - name: Run tests (Swift)
         if: matrix.platform == 'macOS'
-        run: swift test
+        run: swift test

.gitignore

@@ -5,3 +5,4 @@ xcuserdata/
 DerivedData/
 .swiftpm/
 .netrc
+.claude/

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -0,0 +1,118 @@
+# Repository Guidelines
+
+This file is operating guidance for agents and contributors working in `PersistentKeyValueKit`. Keep changes small, explicit, and aligned with the package’s public API guarantees.
+
+> [!IMPORTANT]
+> Use relevant Agent Skills before changing Swift APIs, concurrency code, tests, or technical prose. They capture platform rules and local preferences that code search does not reliably reveal.
+
+## Overview
+
+`PersistentKeyValueKit` is a Swift Package Manager library for type-safe persistence on Apple platforms. It wraps `UserDefaults` and `NSUbiquitousKeyValueStore`, provides SwiftUI property wrappers, and exposes async observation for persistent key changes.
+
+- **Swift tools version**: 6.2
+- **Platforms**: `Package.swift` is the source of truth.
+- **Product**: `PersistentKeyValueKit`
+- **Tests**: XCTest
+- **Runtime resources**: none
+
+## Core Rules
+
+Keep call sites typed. Consumers define a key once, then use that key to read, write, bind, or observe values. Store internals stay inside the package.
+
+Treat public API changes as release decisions. Before adding requirements, changing defaults, renaming symbols, or raising platform minimums, identify the compatibility impact and document the reason.
+
+Do not leak Foundation storage quirks into user-facing APIs. Handle normalization, launch-argument coercion, observation filtering, cancellation, and deregistration inside the package.
+
+## Repository Structure
+
+```text
+├── Package.swift
+├── README.md
+├── Sources/PersistentKeyValueKit/
+│   ├── Async Sequence/
+│   ├── Key-Value Persistible/
+│   ├── Persistent Key/
+│   ├── Persistent Key-Value Representation/
+│   ├── Persistent Key-Value Store/
+│   └── Property Wrapper/
+└── Tests/PersistentKeyValueKitTests/
+    ├── Scaffolding/
+    └── Tests/
+```
+
+Source folders are grouped by feature area. Put new code beside the feature it extends. Keep reusable mocks, observable stores, and custom persistible types in `Tests/PersistentKeyValueKitTests/Scaffolding/`.
+
+## Architecture
+
+`PersistentKeyProtocol` models typed keys. `PersistentKeyValueStore` defines storage operations. `KeyValuePersistible` and `PersistentKeyValueRepresentation` define conversion between Swift values and property-list-compatible storage.
+
+Concrete stores stay thin:
+
+- `UserDefaults`: Foundation defaults plus KVO observation.
+- `NSUbiquitousKeyValueStore`: iCloud key-value storage plus notification observation.
+- `InMemoryPersistentKeyValueStore`: test and ephemeral storage.
+
+Keep `PersistentValue` and `PersistentKeyValues` behavior aligned. SwiftUI observation and async observation should agree on defaults, emitted values, unrelated-key filtering, cancellation, and deregistration unless the difference is intentional and documented.
+
+## Development Commands
+
+Run from the repository root.
+
+```sh
+swift build
+swift test
+swift test --filter PersistentKeyValuesTests
+swift test -c release
+swift test -Xswiftc -strict-concurrency=complete -Xswiftc -warn-concurrency -Xswiftc -enable-actor-data-race-checks
+```
+
+Use the filtered command while iterating. Use strict-concurrency tests for observation, locking, cancellation, or sendability changes. Use release tests for performance-sensitive changes.
+
+## Programming
+
+Preserve existing Swift style: 4-space indentation, grouped declarations, and `// MARK:` sections. Public types use `UpperCamelCase`; properties, functions, and tests use `lowerCamelCase`.
+
+Use the static accessor pattern for reusable keys:
+
+```swift
+extension PersistentKeyProtocol where Self == PersistentKey<Bool> {
+    static var isFeatureEnabled: Self {
+        Self("IsFeatureEnabled", defaultValue: false)
+    }
+}
+```
+
+Check availability before using new Apple APIs. Support every platform minimum in `Package.swift`, or add guarded fallbacks.
+
+Do not add `Sendable` requirements to public value protocols unless the compatibility cost is intentional. Protect shared mutable state explicitly; Foundation store integrations should not force consumers into actor isolation.
+
+Use comments for nonobvious whys only. Public documentation comments should describe behavioral contracts, especially observation lifetime, buffering, storage conversion, and compatibility constraints.
+
+## Testing
+
+Add focused XCTest coverage for every behavior change. Use unique keys such as `key:\(#function)` to avoid cross-test state leakage.
+
+For store behavior, test each affected store. For async observation, cover initial emission, change-only streams, buffering, unrelated keys, cancellation, iterator deinitialization, deregistration, and concurrent cancellation/change races.
+
+## Contributing
+
+Recent commits use short imperative subjects: `Fix UserDefaults launch argument parsing`, `Improve hot path performance`. Match that style and never credit tools or agents.
+
+Before committing, run:
+
+```sh
+git log --oneline -10
+git status --short
+```
+
+Pull requests must list behavior changes, test commands run, and any public API, platform minimum, concurrency, or versioning impact.
+
+## Prose
+
+Read surrounding prose before editing `README.md`, `AGENTS.md`, or long doc comments. Integrate changes into the document’s structure; do not append isolated notes. Tighten wording by default.
+
+Watch for **phantom rationale**: prose that invents a reason for an API shape instead of stating the fact. If an API has two equivalent spellings, say that. Do not explain it with a fake workflow preference.
+
+## Agent-Specific Instructions
+
+Do not overwrite unrelated local changes. Commit when asked. Do not push unless explicitly requested.

Package.swift

@@ -6,7 +6,7 @@ let package = Package(
     name: "PersistentKeyValueKit",
     platforms: [
         .iOS(.v15),
-        .macOS(.v12),
+        .macOS(.v13),
         .tvOS(.v15),
         .visionOS(.v1),
         .watchOS(.v8),

README.md

@@ -33,6 +33,7 @@ PersistentKeyValueKit is backed by a robust test suite.
 - [x] Persistence for any type that conforms to `KeyValuePersistible`.
 - [x] Universal interface for `UserDefaults` and `NSUbiquitousKeyValueStore`.
 - [x] Type-safe property wrapper and view modifier for SwiftUI.
+- [x] AsyncSequence for observing key changes in any context.
 - [x] Built-in support for all primitive (i.e. property list) types.
 - [x] Built-in representations for all common ways to persist values.
 - [x] Keys that are only mutable in Debug builds.
@@ -45,11 +46,10 @@ PersistentKeyValueKit is backed by a robust test suite.
 - tvOS 15.0+
 - visionOS 1.0+
 - watchOS 8.0+
-    - `NSUbiquitousKeyValueStore` requires watchOS 9.0+.
 
 ## Requirements
 
-- Xcode 16.0+
+- Xcode 26.0+
 
 ## Documentation
 
@@ -61,7 +61,7 @@ PersistentKeyValueKit is backed by a robust test suite.
 
 ```swift
 dependencies: [
-    .package(url: "https://github.com/kylehughes/PersistentKeyValueKit.git", .upToNextMajor(from: "1.0.0")),
+    .package(url: "https://github.com/kylehughes/PersistentKeyValueKit.git", .upToNextMajor(from: "1.1.0")),
 ]
 ```
 
@@ -118,6 +118,14 @@ userDefaults.get(.runtimeColorScheme)
 userDefaults.set(.runtimeColorScheme, to: .dark)
 ```
 
+Observe the same key from async code.
+
+```swift
+for await runtimeColorScheme in userDefaults.values(for: .runtimeColorScheme) {
+    apply(runtimeColorScheme)
+}
+```
+
 ## Usage
 
 ### Keys
@@ -415,6 +423,51 @@ extension App: SwiftUI.App {
 }
 ```
 
+### `AsyncSequence`
+
+`PersistentKeyValues` observes a persistent key as an `AsyncSequence`. Use it outside SwiftUI when you want key changes
+without writing KVO or `NotificationCenter` code.
+
+The same sequence is available from the store.
+
+```swift
+for await username in UserDefaults.standard.values(for: .username) {
+    usernameLabel.text = username
+}
+```
+
+It is also available from the key.
+
+```swift
+let usernameKey: PersistentKey<String> = .username
+
+for await username in usernameKey.values(in: UserDefaults.standard) {
+    usernameLabel.text = username
+}
+```
+
+By default, `values(for:)` and `values(in:)` emit the current value first, then later changes.
+
+Use `changes(for:)` or `changes(in:)` to skip the current value and observe only later changes.
+
+```swift
+for await username in UserDefaults.standard.changes(for: .username) {
+    handleChange(username: username)
+}
+```
+
+Pending changes use `.bufferingNewest(1)` by default. If the consumer falls behind, it receives the latest pending
+value instead of an unbounded backlog of intermediate values. Pass `.unbounded` to receive every observed value.
+
+```swift
+for await username in UserDefaults.standard.changes(for: .username, bufferingPolicy: .unbounded) {
+    recordChange(username: username)
+}
+```
+
+Each iterator registers with the store. It deregisters when iteration ends, the iterator is released, or the task is
+cancelled. Iterate from a cancellable task and cancel it when the owner no longer needs updates.
+
 ### `UserDefaults` Registration
 
 PersistentKeyValueKit supports traditional `UserDefaults` registration. The default value of the key will be registered
@@ -512,9 +565,10 @@ affordances for property list safety or proxy representations—but it is availa
 
 There is no platform support for observing changes to keys in `NSUbiquitousKeyValueStore`. The only affordance is
 listening for external changes from other devices. PersistentKeyValueKit implements observability for all mutations
-made through the framework: any `@PersistentValue` using `NSUbiquitousKeyValueStore` will automatically update with any
-changes made by PersistentKeyValueKit anywhere, on any device. However, any changes to `NSUbiquitousKeyValueStore` made 
-outside of the framework will not be automatically reflected in `@PersistentValue` properties.
+made through the framework: any `@PersistentValue` or `AsyncSequence` using `NSUbiquitousKeyValueStore` will
+automatically update with any changes made by PersistentKeyValueKit anywhere, on any device. However, any changes to
+`NSUbiquitousKeyValueStore` made outside of the framework will not be automatically reflected in `@PersistentValue`
+properties or `AsyncSequence` iterations.
 
 ## Contributions