Document RawRepresentable enums and add compatibility tests

Author: fatbobman

README.md

@@ -408,6 +408,25 @@ struct UserPreferences: Codable {
 }
 ```
 
+### Enum RawRepresentable Types
+
+Enums whose `RawValue` already conforms to the property-list set (for example `String`, `Int`, etc.) are persisted automatically via their raw value:
+
+```swift
+enum Theme: String {
+    case light
+    case dark
+    case system
+}
+
+@ObservableDefaults
+class AppearanceSettings {
+    var theme: Theme = Theme.system
+}
+```
+
+Because these enums are handled through `RawRepresentable`, avoid adding an explicit `Codable` conformance to the same type—doing so can introduce ambiguous overloads in the generated storage accessors. If you need custom encoding, wrap the enum in another `Codable` type instead of conforming the enum itself.
+
 ### Integrating with Other Observable Objects
 
 It's recommended to manage storage data separately from your main application state:

README_zh.md

@@ -408,6 +408,25 @@ struct UserPreferences: Codable {
 }
 ```
 
+### Enum RawRepresentable 支持
+
+当枚举的 `RawValue` 本身就是属性列表支持的类型（例如 `String`、`Int` 等）时，宏会自动通过 rawValue 进行持久化：
+
+```swift
+enum Theme: String {
+    case light
+    case dark
+    case system
+}
+
+@ObservableDefaults
+class AppearanceSettings {
+    var theme: Theme = Theme.system
+}
+```
+
+由于这些枚举依赖 `RawRepresentable` 存储，请避免为它们额外声明 `Codable`，否则会在生成的存取器中出现重载歧义。如果需要自定义编码，可在更高层的 `Codable` 模型中包装该枚举，而不是直接让枚举本身符合 `Codable`。
+
 ### 与其他 Observable 对象集成
 
 建议将存储数据与主应用程序状态分开管理：

Sources/ObservableDefaults/NSUbiquitousKeyValueStore/CloudPropertyListValue.swift

@@ -11,6 +11,12 @@ import Foundation
 /// Protocol for types that can be stored in NSUbiquitousKeyValueStore
 public protocol CloudPropertyListValue {}
 
+/// Compatibility shim: legacy projects may still conform to this typealias.
+///
+/// New code can simply conform to `Codable`—this remains only to avoid breaking
+/// existing code and may be removed in a future major release.
+public typealias CodableCloudPropertyListValue = Codable
+
 // Extensions for basic types supported by NSUbiquitousKeyValueStore
 extension String: CloudPropertyListValue {}
 extension Int: CloudPropertyListValue {}

Sources/ObservableDefaults/UserDefaults/UserDefaultsPropertyListValue.swift

@@ -32,6 +32,12 @@ import Foundation
 /// - Note: All conforming types must also be Equatable to support value comparison
 public protocol UserDefaultsPropertyListValue: Equatable {}
 
+/// Compatibility shim: legacy projects may still conform to this typealias.
+///
+/// New code can simply conform to `Codable`—this remains only to avoid breaking
+/// existing code and may be removed in a future major release.
+public typealias CodableUserDefaultsPropertyListValue = Codable
+
 // MARK: - Data Types
 
 /// NSData conforms to UserDefaultsPropertyListValue as it's a fundamental property list type

Tests/ObservableDefaultsTests/CompatibilityTests.swift

@@ -0,0 +1,38 @@
+import Foundation
+import ObservableDefaults
+import Testing
+
+private struct LegacyDefaultsValue: CodableUserDefaultsPropertyListValue, Equatable {
+    var text: String = "legacy"
+}
+
+private struct LegacyCloudValue: CodableCloudPropertyListValue, Equatable {
+    var text: String = "legacy"
+}
+
+@ObservableDefaults
+private class LegacyDefaultsStore {
+    var value = LegacyDefaultsValue()
+}
+
+@ObservableCloud(developmentMode: true)
+private class LegacyCloudStore {
+    var value = LegacyCloudValue()
+}
+
+@Suite("Compatibility Tests")
+struct CompatibilityTests {
+    @Test
+    func defaultsCodableCompatibility() {
+        let store = LegacyDefaultsStore()
+        store.value = LegacyDefaultsValue(text: "updated")
+        #expect(store.value.text == "updated")
+    }
+
+    @Test
+    func cloudCodableCompatibility() {
+        let store = LegacyCloudStore()
+        store.value = LegacyCloudValue(text: "updated")
+        #expect(store.value.text == "updated")
+    }
+}

Tests/ObservableDefaultsTests/EnumRawRepresentableTests.swift

@@ -0,0 +1,36 @@
+import Foundation
+import ObservableDefaults
+import Testing
+
+private enum Color: String {
+    case red
+    case green
+    case blue
+}
+
+@ObservableDefaults
+private class RawValueDefaultsStore {
+    var color: Color = .red
+}
+
+@ObservableCloud(developmentMode: true)
+private class RawValueCloudStore {
+    var color: Color = .red
+}
+
+@Suite("Enum RawRepresentable Tests")
+struct EnumRawRepresentableTests {
+    @Test
+    func defaultsEnumSupport() {
+        let store = RawValueDefaultsStore()
+        store.color = .green
+        #expect(store.color == .green)
+    }
+
+    @Test
+    func cloudEnumSupport() {
+        let store = RawValueCloudStore()
+        store.color = .blue
+        #expect(store.color == .blue)
+    }
+}

Tests/ObservableDefaultsTests/PrefixTests.swift

@@ -85,6 +85,5 @@ func emptyParameters() {
 func emptyPrefixCloud() {
     let test = Test6()
     test.emptyPrefix = "updated"
-    let value = test.emptyPrefix == "updated"
     #expect(test.emptyPrefix == "updated")
 }