LocalPreferences Namespace nesting

Sources/GroveFoundation/LocalPreferences/LocalPreferenceKey.swift

@@ -340,8 +340,12 @@ extension LocalPreferenceKeys {
     /// - ``app``
     /// - ``bundle(_:)``
     /// - ``custom(_:)``
+    ///
+    /// ### Instance Methods
+    /// - ``nested(_:)``
     public struct Namespace: Equatable, Sendable {
-        @usableFromInline let value: String
+        /// The namespace's path. Empty if this is the global namespace.
+        @usableFromInline let path: [String]
 
         /// Checks if this is the global namespace.
         ///
@@ -354,17 +358,13 @@ extension LocalPreferenceKeys {
         }
 
         @inlinable
-        init(value: String) {
-            self.value = value
+        init(path: [String]) {
+            self.path = path
         }
 
         @inlinable
         func format(keyName: String, applyKVOCompatibilityFixes: Bool) -> String {
-            let fullKey = if isGlobal {
-                keyName
-            } else {
-                "\(value):\(keyName)"
-            }
+            let fullKey = (path + [keyName]).joined(separator: ":")
             return if applyKVOCompatibilityFixes {
                 // We want to be able to observe these entries via KVO, which doesn't work if they appear to be keyPaths,
                 // therefore we replace all '.' with '_'.
@@ -373,6 +373,14 @@ extension LocalPreferenceKeys {
                 fullKey
             }
         }
+
+        /// Creates a nested namespace, by appending an inner namespace to the current one.
+        ///
+        /// - Note: Bulk-removing a namespace (via ``LocalPreferencesStore/removeAllEntries(in:)``
+        ///     will also remove all entries belonging to nested namespaces within the outer one.
+        public func nested(_ innerName: String) -> Namespace {
+            Namespace(path: path + [innerName])
+        }
     }
 }
 
@@ -385,7 +393,7 @@ extension LocalPreferenceKeys.Namespace {
 
     /// A special namespace that causes local preference values be written at the global scope.
     @inlinable public static var none: Self {
-        .custom("")
+        .init(path: [])
     }
 
     /// Creates a namespace that scopes keys based on a bundle id.
@@ -396,12 +404,12 @@ extension LocalPreferenceKeys.Namespace {
         guard let bundleId = bundle.bundleIdentifier else {
             return .none
         }
-        return Self(value: bundleId)
+        return Self(path: [bundleId])
     }
 
     /// Creates a namespace that scopes keys based on a custom string.
     @inlinable
     public static func custom(_ value: String) -> Self {
-        Self(value: value)
+        Self(path: [value])
     }
 }

Tests/GroveFoundationTests/LocalPreferenceTests.swift

@@ -15,9 +15,11 @@ import Testing
 
 @Suite(.serialized)
 final class LocalPreferenceTests {
-    let suiteName = "org.grovealliance.GroveFoundation.unitTests"
-    let suite: UserDefaults
-    let store: LocalPreferencesStore
+    private typealias Namespace = LocalPreferenceKeys.Namespace
+
+    private let suiteName = "org.grovealliance.GroveFoundation.unitTests"
+    private let suite: UserDefaults
+    private let store: LocalPreferencesStore
 
     init() throws {
         suite = try #require(UserDefaults(suiteName: suiteName))
@@ -343,12 +345,12 @@ final class LocalPreferenceTests {
 
     @Test
     func namespaceRemoval() {
-        func countEntries(in namespace: LocalPreferenceKeys.Namespace) -> Int {
+        func countEntries(in namespace: Namespace) -> Int {
             store.defaults.dictionaryRepresentation().keys.count { key in
                 key.starts(with: namespace.format(keyName: "", applyKVOCompatibilityFixes: true))
             }
         }
-        func makeKey(_ key: String, in namespace: LocalPreferenceKeys.Namespace) -> LocalPreferenceKey<String> {
+        func makeKey(_ key: String, in namespace: Namespace) -> LocalPreferenceKey<String> {
             .init(LocalPreferenceKey<String>.Key(key, in: namespace), default: "")
         }
 
@@ -398,6 +400,63 @@ final class LocalPreferenceTests {
     }
 
 
+    @Test
+    func nestedNamespaces() {
+        let outerNS: Namespace = .custom("outer")
+        let innerNS = outerNS.nested("inner")
+        #expect(outerNS.format(keyName: "key", applyKVOCompatibilityFixes: false) == "outer:key")
+        #expect(innerNS.format(keyName: "key", applyKVOCompatibilityFixes: false) == "outer:inner:key")
+
+        let outerKey = LocalPreferenceKey<String?>(.init("key", in: outerNS))
+        #expect(outerKey.key.value == "outer:key")
+        let innerKey = LocalPreferenceKey<String?>(.init("key", in: innerNS))
+        #expect(innerKey.key.value == "outer:inner:key")
+
+        #expect(!store.hasEntry(for: outerKey))
+        #expect(!store.hasEntry(for: innerKey))
+        #expect(!store.hasEntry(in: outerNS))
+        #expect(!store.hasEntry(in: innerNS))
+
+        store[outerKey] = "Hey!"
+        #expect(store.hasEntry(for: outerKey))
+        #expect(!store.hasEntry(for: innerKey))
+        #expect(store.hasEntry(in: outerNS))
+        #expect(!store.hasEntry(in: innerNS))
+        #expect(store[outerKey] == "Hey!")
+
+        store[innerKey] = "Hey :)"
+        #expect(store.hasEntry(for: outerKey))
+        #expect(store.hasEntry(for: innerKey))
+        #expect(store.hasEntry(in: outerNS))
+        #expect(store.hasEntry(in: innerNS))
+        #expect(store[outerKey] == "Hey!")
+        #expect(store[innerKey] == "Hey :)")
+
+        // if we clear the inner namespace, its content get removed but those of the outer one remain
+        store.removeAllEntries(in: innerNS)
+        #expect(store.hasEntry(for: outerKey))
+        #expect(!store.hasEntry(for: innerKey))
+        #expect(store.hasEntry(in: outerNS))
+        #expect(!store.hasEntry(in: innerNS))
+        #expect(store[outerKey] == "Hey!")
+        #expect(store[innerKey] == nil)
+
+        // but if we clear the outer ns, the inner one implicitly also gets cleared
+        store[innerKey] = "Hey :)"
+        #expect(store.hasEntry(for: outerKey))
+        #expect(store.hasEntry(for: innerKey))
+        #expect(store.hasEntry(in: outerNS))
+        #expect(store.hasEntry(in: innerNS))
+        #expect(store[outerKey] == "Hey!")
+        #expect(store[innerKey] == "Hey :)")
+        store.removeAllEntries(in: outerNS)
+        #expect(!store.hasEntry(for: outerKey))
+        #expect(!store.hasEntry(for: innerKey))
+        #expect(!store.hasEntry(in: outerNS))
+        #expect(!store.hasEntry(in: innerNS))
+    }
+
+
     // MARK: Migration Testing
 
     private func withTemporarySuiteForMigration(