Migrate to Swift 6.2 strict concurrency

[ulkhan-amiraslanov-paysera]

Summary

Migrate the library to Swift 6.2 strict concurrency. Consumers can drop @preconcurrency import SwiftyUserDefaults and use the library cleanly under Swift 6 language mode. The migration is now concurrency-hardened: the property-wrapper write path is race-free, observer disposal is race-free, and the public Sendable surface is expressed at the type level rather than via blanket @unchecked annotations.

Package

• Bump swift-tools-version to 6.2
• Set swiftLanguageModes: [.v6]
• Enable upcoming features: GlobalActorIsolatedTypesUsability, InferIsolatedConformances, InferSendableFromCaptures, NonisolatedNonsendingByDefault, ExistentialAny
• Bump platform floors to macOS 10.15, iOS 13, tvOS 13, watchOS 6 (required by Swift 6)

Sendable surface

• DefaultsKeys, DefaultsKeyStore, DefaultsAdapter, DefaultsBridge, DefaultsDisposable, DefaultsProviding, SwiftyUserDefaultOptions made Sendable.
• Primitive bridges (String, Int, Double, Bool, Data, URL) are plain Sendable.
• Generic bridges (Object, Array, Codable, KeyedArchiver, RawRepresentable, Optional variants) use conditional Sendable based on their generic parameter — replacing the original blanket @unchecked Sendable. Consumers using non-Sendable T now get a compile-time check instead of a silent unchecked promise.
• DefaultsObserver is @unchecked Sendable; mutable didRemoveObserver state guarded by NSLock.
• SwiftyUserDefault property wrapper is @unchecked Sendable; mutable cache and observation reference guarded by NSRecursiveLock.

Stored-type Sendability (source-breaking)

DefaultsKey, DefaultsObserver, and SwiftyUserDefault now require their stored type to be Sendable:

public struct DefaultsKey<ValueType: DefaultsSerializable> where ValueType.T: Sendable { ... }
public final class DefaultsObserver<T: DefaultsSerializable> ... where T == T.T, T: Sendable { ... }
public final class SwiftyUserDefault<T: DefaultsSerializable> ... where T.T == T, T: Sendable { ... }

With this in place, both DefaultsKey and DefaultsObserver.Update become unconditionally Sendable.

Consumers storing non-Sendable values via DefaultsKey (typically [String: Any] or non-Sendable Codable classes) will need to switch to a Sendable representation ([String: any Sendable] or a typed Codable struct).

The constraint is applied at the generic type level rather than on DefaultsSerializable itself because Swift forbids conditional non-marker conformance based on a marker protocol like Sendable, which prevents constraining the Dictionary where Key == String extension on Value: Sendable.

Race fixes in the new lock paths

The migration added locks where the upstream library had none. Two locks were originally added imperfectly and have since been tightened:

• DefaultsObserver.dispose(): the NSLock now covers the removeObserver call so that an explicit dispose() racing with a deinit-triggered dispose() from another thread cannot both reach removeObserver.
• SwiftyUserDefault setter: switched from NSLock to NSRecursiveLock and the setter now holds the lock across both the _value cache write and the Defaults[key:] = newValue storage write. The KVO observer callback (.observed mode) re-enters the same lock on the same thread synchronously, which is why a non-recursive lock would have deadlocked here.

The result: in .cached (with or without .observed) mode, two concurrent setters serialize and the cache and storage cannot diverge.

Global state

• Defaults global wrapped in nonisolated(unsafe). Kept as var to match the upstream API contract (the original library invites consumers to reassign it for shared-suite use). The (unsafe) annotation makes the existing race-checking opt-out explicit under Swift 6 rather than changing the surface.

Boundary helpers

• New UncheckedSendable<Value> wrapper, internal-scoped, used to hand UserDefaults across isolation boundaries in DefaultsAdapter. Apple documents UserDefaults as thread-safe but does not mark it Sendable.

Observer handlers

• All observer handler closures typed @escaping @Sendable (Update) -> Void.
• The public observe(_:options:handler:) is now documented: the handler is invoked on whichever thread posts the KVO notification (typically the writer's thread), not guaranteed to be the main thread. Dispatch onto your own actor/queue inside the handler if you need a specific isolation.

Property-wrapper option doc

• .cached carries a doc-comment explaining that it should be paired with .observed to avoid a permanently-stale cache after out-of-band writes (other code paths, app extensions writing through the same suite, or another process).

Other

• DefaultsDisposable? → (any DefaultsDisposable)? for ExistentialAny.
• Renamed inner shadowed generic T → U inside Update.deserialize to satisfy stricter generic resolution.

What is NOT changed (intentional behavior preservation)

These belong in separate follow-up changes if pursued, because each alters runtime semantics rather than concurrency annotations:

• The nonisolated(unsafe) var Defaults global — closing it would remove the upstream-documented reassignment pattern.
• try? JSONDecoder().decode(...) in DefaultsCodableBridge and UserDefaults.decodable — pre-existing silent failure on malformed payloads; reliability concern, not concurrency.
• ?? key.defaultValue in DefaultsObserver.Update.init — pre-existing fallback that hides deserialize failures.

Source-breaking changes consumers should know about

1. DefaultsDisposable: Sendable — external conformers must also be Sendable.
2. DefaultsProviding: Sendable — external conformers must also be Sendable.
3. DefaultsKey<T> / DefaultsObserver<T> / SwiftyUserDefault<T> now require T.T: Sendable. The typical migration is [String: Any] → [String: any Sendable] or a typed Codable struct, and Codable class → mark as Sendable.
4. Platform-floor bumps (macOS 10.15, iOS 13, tvOS 13, watchOS 6).

Test plan

• swift build succeeds under Swift 6
• TEST=1 swift test passes the existing Quick/Nimble suite
• New concurrency specs for SwiftyUserDefault and DefaultsObserver pass
• Consumer project compiles without @preconcurrency on the import
• No runtime regressions on observer callbacks (KVO firing thread → handler isolation hop is documented as Sendable)

[gemini-code-assist]

Code Review

This pull request updates the library for Swift 6 strict concurrency by adding Sendable conformances, utilizing the @sendable attribute for closures, and implementing thread-safety via NSLock in observers and property wrappers. It also introduces an UncheckedSendable utility to handle non-Sendable types like UserDefaults. The review feedback suggests enhancing safety and idiomatic correctness by using constant properties (let) for isOptional in DefaultsKey and wrappedValue in UncheckedSendable to ensure immutability.

[MohsenKhosravinia]

The lock is released before the write to Defaults, which means two concurrent setters can interleave so the cache (_value) ends up holding one value while UserDefaults ends up with the other:

T1: lock; _value=A; unlock; ──────────────────── Defaults[key]=A
T2:                       lock; _value=B; unlock; Defaults[key]=B

Result: cache says A, storage says B (or vice versa). The class is declared @unchecked Sendable with a comment claiming the lock makes it safe, but the lock doesn't cover the externally visible mutation. Either hold the lock across the Defaults[key:] write (watch for re-entrancy via KVO observers), or stop caching writes and rely on .observed to repopulate _value.

[ulkhan-amiraslanov-paysera]

Keeping the lock scope as-is. Widening it to cover the Defaults[key:] = newValue write would change the locking model (the observer callback already takes the same lock, so we'd need an NSRecursiveLock to avoid a synchronous-KVO deadlock), and dropping the cache-on-write line would change the observable behavior of the wrapper for callers using .cached without .observed. The interleave you describe is inherent to the upstream cache design and exists pre-migration. Documented the limitation on .cached itself (see e358b66) so callers understand the contract.

[MohsenKhosravinia]

Worth documenting that .cached alone (without .observed) gives a permanently-stale cache the moment anyone writes the key through a different SwiftyUserDefault instance or directly via Defaults. Consider making .observed an implicit requirement of .cached, or at least adding a doc-comment warning on SwiftyUserDefaultOptions.cached.

[ulkhan-amiraslanov-paysera]

Added a doc-comment on .cached pointing this out (e358b66). Made it advisory rather than implicit so we don't change the existing combinator semantics.

[MohsenKhosravinia]

nonisolated(unsafe) var on a public mutable global disables race-checking entirely; nothing prevents a non-startup reassignment from racing with reads on another thread. The doc-comment example ("redefine this global shortcut in your app target") describes shadowing, not mutation — shadowing works with let.

Suggest making this let (consumers shadow with their own var/let in their app target, which is the documented pattern). If keeping it var is required for back-compat, wrap the mutation in an actor / lock-isolated holder and drop the (unsafe) qualifier. Either way, please file/link a follow-up issue per the strict-concurrency migration policy — nonisolated(unsafe) should never be the final state.

[ulkhan-amiraslanov-paysera]

Keeping as nonisolated(unsafe) var to match the upstream API contract (the original library exposes public var Defaults and the docs explicitly invite consumers to reassign it for shared suites). The nonisolated(unsafe) annotation makes the existing race-checking opt-out explicit under Swift 6 rather than changing the surface. A follow-up tightening (actor-isolated holder or let) would be a behavior change and belongs in a separate change.

[MohsenKhosravinia]

These bridges are stateless (only init(), or a single let bridge in the optional wrappers), so they're trivially Sendable whenever T (or Bridge) is. Replace the blanket @unchecked Sendable with conditional conformance:

public struct DefaultsObjectBridge<T>: DefaultsBridge {}
extension DefaultsObjectBridge: Sendable where T: Sendable {}

This keeps Swift 6 happy where it matters and gives consumers a compile-time check if they try to use a non-Sendable T, instead of a silent unchecked promise. Same applies to DefaultsArrayBridge, DefaultsCodableBridge, DefaultsKeyedArchiverBridge, DefaultsRawRepresentableBridge, DefaultsRawRepresentableArrayBridge, DefaultsOptionalBridge, DefaultsOptionalArrayBridge.

[ulkhan-amiraslanov-paysera]

Fixed in e358b66. All seven generic bridges (DefaultsObjectBridge, DefaultsArrayBridge, DefaultsCodableBridge, DefaultsKeyedArchiverBridge, DefaultsRawRepresentableBridge, DefaultsRawRepresentableArrayBridge, DefaultsOptionalBridge, DefaultsOptionalArrayBridge) now use conditional Sendable conformance instead of blanket @unchecked.

[MohsenKhosravinia]

Two things:

1. The handler closure is @Sendable (Update) -> Void, which requires Update to be Sendable. Update contains T.T?, so this only holds if T.T: Sendable. If DefaultsSerializable.T isn't constrained Sendable, this is an implicit promise the type system can't keep — please either constrain DefaultsSerializable.T: Sendable, or add an explicit extension DefaultsObserver.Update: Sendable where T.T: Sendable {}.
2. KVO delivers observeValue on whichever thread fired the change, so the user-provided handler runs on an unspecified thread. Worth adding a doc-comment on the public observe(_:options:handler:) saying "the handler may be invoked on any thread; hop to your own actor if you need isolation."

[ulkhan-amiraslanov-paysera]

Fixed in e358b66, and then strengthened in 2d58b53.

Initial fix added extension DefaultsObserver.Update: Sendable where T.T: Sendable {} (conditional). The follow-up commit 2d58b53 added T: Sendable to DefaultsObserver<T>'s where clause, which makes Update unconditionally Sendable (currently extension DefaultsObserver.Update: Sendable {}).

Also added a threading note on the public observe(_:options:handler:) describing that the handler is invoked on whichever thread posts the KVO notification.

[MohsenKhosravinia]

All stored properties are let, so the only reason @unchecked is needed is that ValueType.T is unconstrained. Prefer structural conformance:

public struct DefaultsKey<ValueType: DefaultsSerializable> { ... }
extension DefaultsKey: Sendable where ValueType.T: Sendable {}

Combined with constraining DefaultsSerializable.T: Sendable (see comment on DefaultsObserver), the @unchecked disappears entirely.

[ulkhan-amiraslanov-paysera]

Fixed in e358b66, then strengthened in 2d58b53.

Initial fix made DefaultsKey conditionally Sendable (extension DefaultsKey: Sendable where ValueType.T: Sendable {}). The follow-up commit 2d58b53 added a generic constraint to the struct itself (where ValueType.T: Sendable), so DefaultsKey is now unconditionally Sendable.

Going via a generic constraint rather than constraining DefaultsSerializable directly because Swift forbids non-marker conditional conformance based on the Sendable marker — extension Dictionary: DefaultsSerializable where Key == String, Value: Sendable hits a compiler wall.

[MohsenKhosravinia]

Consider making this internal (and dropping @frozen/public since neither matters for library-internal use). The wrapper is only used inside DefaultsAdapter; keeping it public invites consumers to reach for an unchecked escape hatch instead of constraining their types properly. The doc-comment already says it's for the one specific UserDefaults boundary — the access level should match.

[ulkhan-amiraslanov-paysera]

Fixed in e358b66. UncheckedSendable is now internal and no longer @Frozen — it is only used inside DefaultsAdapter and was not intended as a public escape hatch.