Fix RawRepresentable & Codable conflict (issue #23)

This commit resolves the compilation ambiguity that occurred when types
conform to both RawRepresentable and Codable protocols.

Changes:
- Add @_disfavoredOverload to Codable methods in UserDefaultsWrapper
- Add @_disfavoredOverload to Codable methods in NSUbiquitousKeyValueStoreWrapper
- Add comprehensive tests for RawRepresentable & Codable types (UserDefaults + Cloud)
- Update documentation to reflect that RawRepresentable takes priority over Codable

When a type conforms to both protocols, the library now prioritizes the
RawRepresentable storage method, ensuring backward compatibility with
existing data and more efficient storage for enum types.

Fixes #23

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: fatbobman

README.md

@@ -436,7 +436,7 @@ class AppearanceSettings {
 }
 ```
 
-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.
+When a type conforms to both `RawRepresentable` and `Codable`, the library will prioritize the `RawRepresentable` storage method, storing values using their raw representation rather than JSON encoding. This ensures backward compatibility with existing data and provides more efficient storage for enum types.
 
 ### Integrating with Other Observable Objects
 

README_zh.md

@@ -436,7 +436,7 @@ class AppearanceSettings {
 }
 ```
 
-由于这些枚举依赖 `RawRepresentable` 存储，请避免为它们额外声明 `Codable`，否则会在生成的存取器中出现重载歧义。如果需要自定义编码，可在更高层的 `Codable` 模型中包装该枚举，而不是直接让枚举本身符合 `Codable`。
+当类型同时遵循 `RawRepresentable` 和 `Codable` 时，库会优先使用 `RawRepresentable` 的存储方式，通过原始值（raw value）存储数据，而不是使用 JSON 编码。这确保了与现有数据的向后兼容性，并为枚举类型提供了更高效的存储方式。
 
 ### 与其他 Observable 对象集成
 

Sources/ObservableDefaults/NSUbiquitousKeyValueStore/NSUbiquitousKeyValueStoreWrapper.swift

@@ -147,6 +147,7 @@ public struct NSUbiquitousKeyValueStoreWrapper: Sendable {
     ///   - defaultValue: The default value to return if the key is not found or decoding fails
     /// - Returns: The decoded value from the store, or the default value if the key is not found or
     /// decoding fails
+    @_disfavoredOverload
     public func getValue<Value>(
         _ key: String,
         _ defaultValue: Value) -> Value
@@ -172,6 +173,7 @@ public struct NSUbiquitousKeyValueStoreWrapper: Sendable {
     ///   - defaultValue: The default optional value to return if the key is not found or decoding fails
     /// - Returns: The decoded optional value from the store, or the default value if the key is not found or
     /// decoding fails
+    @_disfavoredOverload
     public func getValue<Value>(
         _ key: String,
         _ defaultValue: Value?) -> Value?
@@ -309,6 +311,7 @@ public struct NSUbiquitousKeyValueStoreWrapper: Sendable {
     ///   - key: The key to set the value for
     ///   - newValue: The new Codable value to store
     /// - Note: If encoding fails, the method silently returns without storing anything
+    @_disfavoredOverload
     public func setValue<Value: Codable>(
         _ key: String,
         _ newValue: Value) {
@@ -324,6 +327,7 @@ public struct NSUbiquitousKeyValueStoreWrapper: Sendable {
     ///   - key: The key to set the value for
     ///   - newValue: The new optional Codable value to store (nil will remove the key)
     /// - Note: If encoding fails, the method silently returns without storing anything
+    @_disfavoredOverload
     public func setValue<Value: Codable>(
         _ key: String,
         _ newValue: Value?)

Sources/ObservableDefaults/UserDefaults/UserDefaultsWrapper.swift

@@ -171,6 +171,7 @@ public struct UserDefaultsWrapper<Value> {
     ///   - store: The user defaults store to get the value from
     /// - Returns: The decoded value from the user defaults store, or the default value if the key
     /// is not found or decoding fails
+    @_disfavoredOverload
     public nonisolated static func getValue(
         _ key: String,
         _ defaultValue: Value,
@@ -198,6 +199,7 @@ public struct UserDefaultsWrapper<Value> {
     ///   - store: The user defaults store to get the value from
     /// - Returns: The decoded optional value from the user defaults store, or the default value if the key
     /// is not found or decoding fails
+    @_disfavoredOverload
     public nonisolated static func getValue(
         _ key: String,
         _ defaultValue: Value?,
@@ -307,6 +309,7 @@ public struct UserDefaultsWrapper<Value> {
     ///   - newValue: The new Codable value to store
     ///   - store: The user defaults store to set the value in
     /// - Note: If encoding fails, the method silently returns without storing anything
+    @_disfavoredOverload
     public nonisolated static func setValue(_ key: String, _ newValue: Value, _ store: UserDefaults)
     where Value: Codable {
         // Encode the value to JSON data
@@ -322,6 +325,7 @@ public struct UserDefaultsWrapper<Value> {
     ///   - newValue: The new optional Codable value to store (nil will remove the key)
     ///   - store: The user defaults store to set the value in
     /// - Note: If encoding fails, the method silently returns without storing anything
+    @_disfavoredOverload
     public nonisolated static func setValue(_ key: String, _ newValue: Value?, _ store: UserDefaults)
     where Value: Codable {
         guard let value = newValue else {

Tests/ObservableDefaultsTests/RawRepresentableCodableTests.swift

@@ -0,0 +1,219 @@
+import Foundation
+import ObservableDefaults
+import Testing
+
+// Test type that conforms to both RawRepresentable and Codable
+// This simulates the user's scenario from issue #23
+private struct UserProfile: RawRepresentable, Equatable {
+    var name: String
+    var age: Int
+
+    // RawRepresentable conformance using JSON string
+    var rawValue: String {
+        // Manually construct JSON to avoid Codable encoding
+        return "{\"name\": \"\(name)\", \"age\": \(age)}"
+    }
+
+    init?(rawValue: String) {
+        // Simple JSON parsing for test purposes
+        guard let data = rawValue.data(using: .utf8),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+              let name = json["name"] as? String,
+              let age = json["age"] as? Int else {
+            return nil
+        }
+        self.name = name
+        self.age = age
+    }
+
+    init(name: String, age: Int) {
+        self.name = name
+        self.age = age
+    }
+}
+
+// Make it Codable for testing the conflict scenario
+extension UserProfile: Codable {
+    enum CodingKeys: String, CodingKey {
+        case name
+        case age
+    }
+}
+
+// Optional version test
+private enum Status: String, Codable {
+    case active
+    case inactive
+}
+
+@ObservableDefaults(prefix: "Test1_")
+private class TestStore1 {
+    var profile = UserProfile(name: "Default", age: 0)
+}
+
+@ObservableDefaults(prefix: "Test2_")
+private class TestStore2 {
+    var profile = UserProfile(name: "Default", age: 0)
+}
+
+@ObservableDefaults(prefix: "Test3_")
+private class TestStore3 {
+    var optionalProfile: UserProfile?
+}
+
+@ObservableDefaults(prefix: "Test4_")
+private class TestStore4 {
+    var status = Status.active
+}
+
+@ObservableCloud(prefix: "CloudTest1_", developmentMode: true)
+private class CloudTestStore1 {
+    var profile = UserProfile(name: "Default", age: 0)
+}
+
+@ObservableCloud(prefix: "CloudTest2_", developmentMode: true)
+private class CloudTestStore2 {
+    var profile = UserProfile(name: "Default", age: 0)
+}
+
+@ObservableCloud(prefix: "CloudTest3_", developmentMode: true)
+private class CloudTestStore3 {
+    var optionalProfile: UserProfile?
+}
+
+@ObservableCloud(prefix: "CloudTest4_", developmentMode: true)
+private class CloudTestStore4 {
+    var status = Status.active
+}
+
+@Suite("RawRepresentable & Codable Conflict Tests")
+struct RawRepresentableCodableTests {
+
+    @Test("Type conforming to both RawRepresentable and Codable should compile")
+    func compilationTest() {
+        // This test verifies that the code compiles without ambiguity errors
+        let store = TestStore1()
+        #expect(store.profile.name == "Default")
+        #expect(store.profile.age == 0)
+    }
+
+    @Test("Should use RawRepresentable storage (not Codable JSON encoding)")
+    func storageFormatTest() {
+        let store = TestStore2()
+        let testProfile = UserProfile(name: "Alice", age: 30)
+
+        store.profile = testProfile
+
+        // Verify the value is stored correctly
+        #expect(store.profile.name == "Alice")
+        #expect(store.profile.age == 30)
+
+        // Check that it's stored as a String (RawRepresentable way), not as Data (Codable way)
+        let userDefaults = UserDefaults.standard
+        let storedValue = userDefaults.object(forKey: "Test2_profile")
+
+        // Should be stored as String (raw value), not Data (Codable encoding)
+        #expect(storedValue is String)
+        #expect(storedValue is Data == false)
+    }
+
+    @Test("Should read existing RawRepresentable data correctly")
+    func backwardCompatibilityTest() {
+        let userDefaults = UserDefaults.standard
+        let key = "testProfile"
+
+        // Simulate existing data stored as RawRepresentable (JSON string)
+        let existingProfile = UserProfile(name: "Bob", age: 25)
+        userDefaults.set(existingProfile.rawValue, forKey: key)
+
+        // Read it back using the wrapper
+        let retrieved = UserDefaultsWrapper<UserProfile>.getValue(
+            key,
+            UserProfile(name: "Default", age: 0),
+            userDefaults
+        )
+
+        #expect(retrieved.name == "Bob")
+        #expect(retrieved.age == 25)
+
+        // Cleanup
+        userDefaults.removeObject(forKey: key)
+    }
+
+    @Test("Optional RawRepresentable & Codable type should work")
+    func optionalTest() {
+        let store = TestStore3()
+
+        #expect(store.optionalProfile == nil)
+
+        store.optionalProfile = UserProfile(name: "Charlie", age: 35)
+        #expect(store.optionalProfile?.name == "Charlie")
+        #expect(store.optionalProfile?.age == 35)
+
+        store.optionalProfile = nil
+        #expect(store.optionalProfile == nil)
+    }
+
+    @Test("Enum with RawRepresentable and Codable should work")
+    func enumTest() {
+        // Clean up to ensure fresh state
+        UserDefaults.standard.removeObject(forKey: "Test4_status")
+
+        let store = TestStore4()
+
+        #expect(store.status == .active)
+
+        store.status = .inactive
+        #expect(store.status == .inactive)
+
+        // Verify it's stored as raw value (String), not encoded Data
+        let userDefaults = UserDefaults.standard
+        let storedValue = userDefaults.object(forKey: "Test4_status")
+        #expect(storedValue is String)
+        #expect((storedValue as? String) == "inactive")
+    }
+
+    // MARK: - Cloud Tests
+
+    @Test("Cloud: Type conforming to both RawRepresentable and Codable should compile")
+    func cloudCompilationTest() {
+        let store = CloudTestStore1()
+        #expect(store.profile.name == "Default")
+        #expect(store.profile.age == 0)
+    }
+
+    @Test("Cloud: Should use RawRepresentable storage (not Codable JSON encoding)")
+    func cloudStorageFormatTest() {
+        let store = CloudTestStore2()
+        let testProfile = UserProfile(name: "Alice", age: 30)
+
+        store.profile = testProfile
+
+        #expect(store.profile.name == "Alice")
+        #expect(store.profile.age == 30)
+    }
+
+    @Test("Cloud: Optional RawRepresentable & Codable type should work")
+    func cloudOptionalTest() {
+        let store = CloudTestStore3()
+
+        #expect(store.optionalProfile == nil)
+
+        store.optionalProfile = UserProfile(name: "Charlie", age: 35)
+        #expect(store.optionalProfile?.name == "Charlie")
+        #expect(store.optionalProfile?.age == 35)
+
+        store.optionalProfile = nil
+        #expect(store.optionalProfile == nil)
+    }
+
+    @Test("Cloud: Enum with RawRepresentable and Codable should work")
+    func cloudEnumTest() {
+        let store = CloudTestStore4()
+
+        #expect(store.status == .active)
+
+        store.status = .inactive
+        #expect(store.status == .inactive)
+    }
+}

Tests/ObservableDefaultsTests/SimpleRawRepresentableCodableTest.swift

@@ -0,0 +1,38 @@
+import Foundation
+import ObservableDefaults
+import Testing
+
+// Minimal test to verify compilation works
+private struct TestType: RawRepresentable, Codable, Equatable {
+    var value: String
+
+    var rawValue: String {
+        value
+    }
+
+    init?(rawValue: String) {
+        self.value = rawValue
+    }
+
+    init(value: String) {
+        self.value = value
+    }
+}
+
+@ObservableDefaults(prefix: "SimpleTest_")
+private class SimpleStore {
+    var test = TestType(value: "default")
+}
+
+@Suite("Simple RawRepresentable & Codable Test")
+struct SimpleRawRepresentableCodableTest {
+    @Test
+    func verifyCompilation() {
+        // Clean up UserDefaults before test
+        UserDefaults.standard.removeObject(forKey: "SimpleTest_test")
+
+        let store = SimpleStore()
+        store.test = TestType(value: "updated")
+        #expect(store.test.value == "updated")
+    }
+}