Fix issue #26 overload resolution and document storage rules

Author: fatbobman

README.md

@@ -446,6 +446,58 @@ class AppearanceSettings {
 
 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.
 
+### Storage Resolution Rules (Important for Direct Key Access)
+
+These rules apply to both `@ObservableDefaults` (`UserDefaults`) and `@ObservableCloud` (`NSUbiquitousKeyValueStore`).
+When a type matches multiple constraints, the implementation chooses the most specific path in this order:
+
+1. `RawRepresentable & PropertyListValue & Codable`
+2. `RawRepresentable & PropertyListValue`
+3. `RawRepresentable` (where `RawValue` is a PropertyList-compatible type)
+4. `PropertyListValue & Codable`
+5. `PropertyListValue`
+6. `Codable` only (JSON `Data` path; intentionally lower priority)
+
+#### Persisted Format by Type Combination
+
+- `RawRepresentable`-based paths: persist `rawValue`.
+  - Example: `String`/`Int` raw values are stored directly as `String`/`Int`.
+- `PropertyListValue` paths: persist the value directly as PropertyList-compatible objects.
+- `Codable`-only path: persist JSON-encoded `Data`.
+- Optional values:
+  - non-`nil`: stored using the same rules above
+  - `nil`: key is removed
+
+#### Read Fallback for Compatibility
+
+For `RawRepresentable & PropertyListValue` (including `RawRepresentable & PropertyListValue & Codable`):
+
+- Read attempts `rawValue` format first.
+- If that fails, read falls back to direct `PropertyListValue` casting.
+
+This fallback keeps older data readable when a property was previously persisted via direct PropertyList format and later evolved to a `RawRepresentable` type.
+
+#### Consistency for Manual `UserDefaults` / Cloud Reads and Writes
+
+If you also read/write these keys directly outside the macros, use the same format rules to avoid mismatches.
+
+- Use `rawValue` for all `RawRepresentable`-based properties.
+- Use direct PropertyList values for PropertyList paths.
+- Use JSON `Data` only for `Codable`-only properties.
+- Key naming follows macro key resolution:
+  - default: `prefix + propertyName`
+  - custom key: `@DefaultsKey` / `@CloudKey`
+
+Example (`UserDefaults`):
+
+```swift
+// For RawRepresentable-backed property (rawValue: String)
+defaults.set(theme.rawValue, forKey: "app_theme")
+
+// For Codable-only property
+defaults.set(try JSONEncoder().encode(profile), forKey: "app_profile")
+```
+
 ### Integrating with Other Observable Objects
 
 It's recommended to manage storage data separately from your main application state:

README_zh.md

@@ -446,6 +446,58 @@ class AppearanceSettings {
 
 当类型同时遵循 `RawRepresentable` 和 `Codable` 时，库会优先使用 `RawRepresentable` 的存储方式，通过原始值（raw value）存储数据，而不是使用 JSON 编码。这确保了与现有数据的向后兼容性，并为枚举类型提供了更高效的存储方式。
 
+### 存储决策规则（直接访问 Key 时请务必遵循）
+
+以下规则同时适用于 `@ObservableDefaults`（`UserDefaults`）和 `@ObservableCloud`（`NSUbiquitousKeyValueStore`）。
+当类型同时满足多个约束时，按“越具体越优先”的顺序选择：
+
+1. `RawRepresentable & PropertyListValue & Codable`
+2. `RawRepresentable & PropertyListValue`
+3. `RawRepresentable`（且 `RawValue` 为 PropertyList 可存储类型）
+4. `PropertyListValue & Codable`
+5. `PropertyListValue`
+6. 仅 `Codable`（JSON `Data` 路径，优先级最低）
+
+#### 各组合的实际存储格式
+
+- `RawRepresentable` 路径：保存 `rawValue`。
+  - 例如 `String`/`Int` rawValue 会直接以 `String`/`Int` 存储。
+- `PropertyListValue` 路径：直接以 PropertyList 值存储。
+- 仅 `Codable` 路径：以 JSON 编码后的 `Data` 存储。
+- Optional 值：
+  - 非 `nil`：按上述规则保存
+  - `nil`：删除对应 key
+
+#### 读取回退（兼容历史数据）
+
+对于 `RawRepresentable & PropertyListValue`（包括 `RawRepresentable & PropertyListValue & Codable`）：
+
+- 读取时先按 `rawValue` 格式解析。
+- 若失败，再回退到直接 `PropertyListValue` 转换。
+
+这保证了历史上“按 PropertyList 直接写入”的旧数据，在后来属性演进为 `RawRepresentable` 后仍可读取。
+
+#### 与手动读写保持一致
+
+如果你在其他位置直接读写 `UserDefaults` / iCloud key，请使用同样的格式规则：
+
+- `RawRepresentable` 相关属性：手动写 `rawValue`
+- `PropertyListValue` 属性：手动写 PropertyList 原值
+- 仅 `Codable` 属性：手动写 JSON `Data`
+- key 规则与宏一致：
+  - 默认：`prefix + propertyName`
+  - 自定义 key：`@DefaultsKey` / `@CloudKey`
+
+示例（`UserDefaults`）：
+
+```swift
+// RawRepresentable 属性（rawValue: String）
+defaults.set(theme.rawValue, forKey: "app_theme")
+
+// 仅 Codable 属性
+defaults.set(try JSONEncoder().encode(profile), forKey: "app_profile")
+```
+
 ### 与其他 Observable 对象集成
 
 建议将存储数据与主应用程序状态分开管理：

Sources/ObservableDefaults/NSUbiquitousKeyValueStore/NSUbiquitousKeyValueStoreWrapper.swift

@@ -82,6 +82,92 @@ public struct NSUbiquitousKeyValueStoreWrapper: Sendable {
         return R(rawValue: rawValue) ?? defaultValue
     }
 
+    /// Gets a value for types that conform to both RawRepresentable and CloudPropertyListValue.
+    ///
+    /// This dedicated overload removes ambiguity between the RawRepresentable and
+    /// CloudPropertyListValue overload sets.
+    public func getValue<Value>(
+        _ key: String,
+        _ defaultValue: Value) -> Value
+    where Value: RawRepresentable, Value.RawValue: CloudPropertyListValue,
+        Value: CloudPropertyListValue {
+        // Prefer RawRepresentable storage for hybrid types.
+        // Fallback to direct property-list casting to preserve compatibility with
+        // legacy data written through non-raw paths.
+        if let rawValue = store.object(forKey: key) as? Value.RawValue {
+            return Value(rawValue: rawValue) ?? defaultValue
+        }
+        if let value = store.object(forKey: key) as? Value {
+            return value
+        }
+        return defaultValue
+    }
+
+    /// Gets an optional value for types that conform to both RawRepresentable and
+    /// CloudPropertyListValue.
+    ///
+    /// This dedicated overload removes ambiguity between the RawRepresentable and
+    /// CloudPropertyListValue overload sets.
+    public func getValue<R>(
+        _ key: String,
+        _ defaultValue: R?) -> R?
+    where R: RawRepresentable, R.RawValue: CloudPropertyListValue, R: CloudPropertyListValue {
+        // Prefer RawRepresentable storage for hybrid types.
+        // Fallback to direct property-list casting to preserve compatibility with
+        // legacy data written through non-raw paths.
+        if let rawValue = store.object(forKey: key) as? R.RawValue {
+            return R(rawValue: rawValue) ?? defaultValue
+        }
+        if let value = store.object(forKey: key) as? R {
+            return value
+        }
+        return defaultValue
+    }
+
+    /// Gets a value for types that conform to RawRepresentable,
+    /// CloudPropertyListValue, and Codable.
+    ///
+    /// This dedicated overload removes ambiguity with the
+    /// CloudPropertyListValue & Codable overload set.
+    public func getValue<Value>(
+        _ key: String,
+        _ defaultValue: Value) -> Value
+    where Value: RawRepresentable, Value.RawValue: CloudPropertyListValue,
+        Value: CloudPropertyListValue & Codable {
+        // Prefer RawRepresentable storage for hybrid types.
+        // Fallback to direct property-list casting to preserve compatibility with
+        // legacy data written through non-raw paths.
+        if let rawValue = store.object(forKey: key) as? Value.RawValue {
+            return Value(rawValue: rawValue) ?? defaultValue
+        }
+        if let value = store.object(forKey: key) as? Value {
+            return value
+        }
+        return defaultValue
+    }
+
+    /// Gets an optional value for types that conform to RawRepresentable,
+    /// CloudPropertyListValue, and Codable.
+    ///
+    /// This dedicated overload removes ambiguity with the
+    /// CloudPropertyListValue & Codable overload set.
+    public func getValue<R>(
+        _ key: String,
+        _ defaultValue: R?) -> R?
+    where R: RawRepresentable, R.RawValue: CloudPropertyListValue,
+        R: CloudPropertyListValue & Codable {
+        // Prefer RawRepresentable storage for hybrid types.
+        // Fallback to direct property-list casting to preserve compatibility with
+        // legacy data written through non-raw paths.
+        if let rawValue = store.object(forKey: key) as? R.RawValue {
+            return R(rawValue: rawValue) ?? defaultValue
+        }
+        if let value = store.object(forKey: key) as? R {
+            return value
+        }
+        return defaultValue
+    }
+
     /// Gets a basic property list value from the ubiquitous key-value store.
     /// This method is used for basic types like String, Int, Bool, etc.
     /// - Parameters:
@@ -245,6 +331,68 @@ public struct NSUbiquitousKeyValueStoreWrapper: Sendable {
         }
     }
 
+    /// Sets a value for types that conform to both RawRepresentable and CloudPropertyListValue.
+    ///
+    /// This dedicated overload removes ambiguity between the RawRepresentable and
+    /// CloudPropertyListValue overload sets.
+    public func setValue<Value>(
+        _ key: String,
+        _ newValue: Value)
+    where Value: RawRepresentable, Value.RawValue: CloudPropertyListValue,
+        Value: CloudPropertyListValue {
+        // Prefer RawRepresentable storage for hybrid types.
+        store.set(newValue.rawValue, forKey: key)
+    }
+
+    /// Sets an optional value for types that conform to both RawRepresentable and
+    /// CloudPropertyListValue.
+    ///
+    /// This dedicated overload removes ambiguity between the RawRepresentable and
+    /// CloudPropertyListValue overload sets.
+    public func setValue<R>(
+        _ key: String,
+        _ newValue: R?)
+    where R: RawRepresentable, R.RawValue: CloudPropertyListValue, R: CloudPropertyListValue {
+        // Prefer RawRepresentable storage for hybrid types.
+        if let newValue {
+            store.set(newValue.rawValue, forKey: key)
+        } else {
+            store.removeObject(forKey: key)
+        }
+    }
+
+    /// Sets a value for types that conform to RawRepresentable,
+    /// CloudPropertyListValue, and Codable.
+    ///
+    /// This dedicated overload removes ambiguity with the
+    /// CloudPropertyListValue & Codable overload set.
+    public func setValue<Value>(
+        _ key: String,
+        _ newValue: Value)
+    where Value: RawRepresentable, Value.RawValue: CloudPropertyListValue,
+        Value: CloudPropertyListValue & Codable {
+        // Prefer RawRepresentable storage for hybrid types.
+        store.set(newValue.rawValue, forKey: key)
+    }
+
+    /// Sets an optional value for types that conform to RawRepresentable,
+    /// CloudPropertyListValue, and Codable.
+    ///
+    /// This dedicated overload removes ambiguity with the
+    /// CloudPropertyListValue & Codable overload set.
+    public func setValue<R>(
+        _ key: String,
+        _ newValue: R?)
+    where R: RawRepresentable, R.RawValue: CloudPropertyListValue,
+        R: CloudPropertyListValue & Codable {
+        // Prefer RawRepresentable storage for hybrid types.
+        if let newValue {
+            store.set(newValue.rawValue, forKey: key)
+        } else {
+            store.removeObject(forKey: key)
+        }
+    }
+
     /// Sets a basic property list value in the ubiquitous key-value store.
     /// This method stores basic types like String, Int, Bool, etc.
     /// - Parameters: