refactor: remove emitInitial flag from publishers

Simplify publisher APIs by removing the emitInitial flag. Publishers
now consistently emit the current value upon subscription and only
future updates are optionally filtered with `.dropFirst()`. This
unification reduces complexity and aligns behavior across different
cache strategies. Updated tests to reflect the new behavior. Also
added specific tests for the namespace-limited clearing functions
in the core Pandora API to enhance flexibility in data management.

Author: joshgallantt

README.md

@@ -11,7 +11,7 @@
 
 [![Swift](https://img.shields.io/badge/Swift-5.9%2B-orange.svg?style=flat)](https://swift.org)
 [![SPM ready](https://img.shields.io/badge/SPM-ready-brightgreen.svg?style=flat-square)](https://swift.org/package-manager/)
-[![Coverage](https://img.shields.io/badge/Coverage-97.1%25-brightgreen.svg?style=flat)](#)
+[![Coverage](https://img.shields.io/badge/Coverage-98%2B%25-brightgreen.svg?style=flat)](#)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![Size](https://img.shields.io/badge/Package_Size-1.5MB-purple.svg?style=flat-square)](#)
 
@@ -59,7 +59,7 @@ A powerful, type-safe caching library for Swift that provides multiple storage s
 - Built on **Swift Concurrency** (`async/await`)  
 - **Actor isolation** for safe persistence without manual locks  
 - Generic, type-safe APIs  
-- **Combine** publishers for reactive data flow  
+- **Combine** publishers for reactive data flow with simplified API  
 
 ⚡ **Performance**
 - LRU eviction in memory & disk
@@ -283,8 +283,8 @@ cache.publisher(for: "current_user")
     }
     .store(in: &cancellables)
 
-// Observe only future changes (skip current value)
-cache.publisher(for: "current_user", emitInitial: false)
+// Observe changes (current value is always emitted)
+cache.publisher(for: "current_user")
     .compactMap { $0 }
     .sink { user in
         print("User changed: \(user.name)")
@@ -301,31 +301,41 @@ cache.publisher(for: "user_id")
         // Handle user details
     }
     .store(in: &cancellables)
+
+// Skip initial value if you only want future updates
+cache.publisher(for: "current_user")
+    .dropFirst() // Skip the immediate current value emission
+    .compactMap { $0 }
+    .sink { user in
+        print("User changed: \(user.name)")
+    }
+    .store(in: &cancellables)
 ```
 
-#### Publisher Options
+#### Publisher Behavior
 
-All Pandora publishers support an `emitInitial` parameter to control whether the current value is emitted immediately upon subscription:
+All Pandora publishers emit the current value immediately upon subscription, followed by any future changes:
 
-- `publisher(for: "key")` - Emits current value immediately (default behavior)
-- `publisher(for: "key", emitInitial: true)` - Explicitly emit current value
-- `publisher(for: "key", emitInitial: false)` - Only emit future changes
+- `publisher(for: "key")` - Emits current value immediately, then future changes
+- Use `.dropFirst()` if you only want to observe future changes, not the current value
 
 ### Cache Cleanup
 
 ```swift
-// Clear specific cache
-cache.clear()
-await diskCache.clear()
-
-// Remove all Pandora disk caches for this app
-Pandora.clearAllDiskData()
-
-// Remove all keys from this app's UserDefaults and iCloud KVS
-Pandora.clearUserDefaults()
-
-// Remove everything above (nuclear option)
-Pandora.deleteAllLocalStorage()
+// Clear specific cache instances
+memoryCache.clear()                    // Synchronous for MemoryBox
+await diskCache.clear()                // Asynchronous for DiskBox
+await hybridCache.clear()              // Asynchronous for HybridBox
+await userDefaultsCache.clear()        // Asynchronous for UserDefaultsBox
+
+// Clear specific namespaces
+Pandora.clearUserDefaults(for: "my_settings")    // Clear specific UserDefaults namespace
+Pandora.clearDiskData(for: "my_cache")           // Clear specific disk namespace
+
+// Clear all data
+Pandora.clearAllUserDefaults()         // Clear all Pandora UserDefaults data
+Pandora.clearAllDiskData()             // Clear all Pandora disk caches
+Pandora.deleteAllLocalStorage()        // Nuclear option - clear everything
 ```
 
 ## Thread Safety

Sources/Pandora/HybridBox/PandoraHybridBox.swift

@@ -47,17 +47,13 @@ public final class PandoraHybridBox<Key: Hashable & Codable & Sendable, Value: C
         self.diskExpiresAfter = diskExpiresAfter
     }
 
-    public func publisher(for key: Key, emitInitial: Bool = true) -> AnyPublisher<Value?, Never> {
-        if emitInitial {
-            let currentValue = syncLock.withLock { memory.get(key) }
-            return Publishers.Merge(
-                Just(currentValue).eraseToAnyPublisher(),
-                memory.publisher(for: key, emitInitial: false)
-            )
-            .eraseToAnyPublisher()
-        } else {
-            return memory.publisher(for: key, emitInitial: false)
-        }
+    public func publisher(for key: Key) -> AnyPublisher<Value?, Never> {
+        let currentValue = syncLock.withLock { memory.get(key) }
+        return Publishers.Merge(
+            Just(currentValue).eraseToAnyPublisher(),
+            memory.publisher(for: key).dropFirst()
+        )
+        .eraseToAnyPublisher()
     }
 
     public func get(_ key: Key) async -> Value? {
@@ -122,15 +118,13 @@ public final class PandoraHybridBox<Key: Hashable & Codable & Sendable, Value: C
         }
     }
 
-    public func clear() {
+    public func clear() async {
         // Clear memory immediately
         syncLock.withLock {
             memory.clear()
         }
 
-        // Clear disk asynchronously
-        Task {
-            await disk.clear()
-        }
+        // Clear disk
+        await disk.clear()
     }
 }

Sources/Pandora/HybridBox/PandoraHybridBoxProtocol.swift

@@ -15,7 +15,7 @@ public protocol PandoraHybridBoxProtocol: Sendable {
     associatedtype Key: Hashable & Codable
     associatedtype Value: Codable
 
-    /// The unique namespace isolating this cache’s memory and disk entries.
+    /// The unique namespace isolating this cache's memory and disk entries.
     var namespace: String { get }
 
     /// A publisher emitting the current and subsequent value for the given key.
@@ -24,8 +24,7 @@ public protocol PandoraHybridBoxProtocol: Sendable {
     /// - Events are sent immediately for memory changes.
     /// - Parameters:
     ///   - key: The cache key to observe.
-    ///   - emitInitial: Whether to emit the current value immediately upon subscription. Defaults to `true`.
-    func publisher(for key: Key, emitInitial: Bool) -> AnyPublisher<Value?, Never>
+    func publisher(for key: Key) -> AnyPublisher<Value?, Never>
 
     /// Reads a value for the given key, checking memory first, then disk.
     ///
@@ -45,5 +44,5 @@ public protocol PandoraHybridBoxProtocol: Sendable {
     func remove(_ key: Key)
 
     /// Clears all values from memory and disk for this instance.
-    func clear()
+    func clear() async
 }

Sources/Pandora/MemoryBox/PandoraMemoryBox.swift

@@ -102,30 +102,35 @@ public class PandoraMemoryBox<Key: Hashable & Sendable, Value: Sendable>: Pandor
         removedSubject?.send(nil)
     }
 
-    public func publisher(for key: Key, emitInitial: Bool = true) -> AnyPublisher<Value?, Never> {
+    public func publisher(for key: Key) -> AnyPublisher<Value?, Never> {
+        let currentValue: Value? = lock.withLock {
+            if let entry = storage[key], !isEntryExpired(entry) {
+                return entry.value
+            } else {
+                return nil
+            }
+        }
+        
+        return Publishers.Merge(
+            Just(currentValue).eraseToAnyPublisher(),
+            getOrCreateMemoryPublisher(for: key).dropFirst()
+        )
+        .eraseToAnyPublisher()
+    }
+    
+    private func getOrCreateMemoryPublisher(for key: Key) -> AnyPublisher<Value?, Never> {
         lock.lock()
         let subject: CurrentValueSubject<Value?, Never>
         if let existing = subjects[key] {
             subject = existing
         } else {
-            let value: Value? = {
-                if let entry = storage[key], !isEntryExpired(entry) {
-                    return entry.value
-                } else {
-                    return nil
-                }
-            }()
-            subject = .init(value)
+            subject = .init(nil) // Start with nil, will be updated by put/remove
             subjects[key] = subject
         }
         let publisher = subject.eraseToAnyPublisher()
         lock.unlock()
 
-        if emitInitial {
-            return publisher
-        } else {
-            return publisher.dropFirst().eraseToAnyPublisher()
-        }
+        return publisher
     }
 
     public func clear() {

Sources/Pandora/MemoryBox/PandoraMemoryBoxProtocol.swift

@@ -31,6 +31,5 @@ public protocol PandoraMemoryBoxProtocol {
     /// Returns a publisher that emits the current and subsequent values for the given key.
     /// - Parameters:
     ///   - key: The cache key to observe.
-    ///   - emitInitial: Whether to emit the current value immediately upon subscription. Defaults to `true`.
-    func publisher(for key: Key, emitInitial: Bool) -> AnyPublisher<Value?, Never>
+    func publisher(for key: Key) -> AnyPublisher<Value?, Never>
 }

Sources/Pandora/Pandora.swift

@@ -320,33 +320,74 @@ public enum Pandora {
 
     // MARK: - Utilities
 
-    /// Deletes all disk cache data created by `Pandora.Disk` and `Pandora.Hybrid`.
+    /// Clears all UserDefaults and iCloud data for a specific namespace.
+    ///
+    /// - Parameter namespace: The namespace to clear.
+    public static func clearUserDefaults(for namespace: String) {
+        let defaults = Foundation.UserDefaults.standard
+        let store = NSUbiquitousKeyValueStore.default
+        
+        // Get all keys and filter by namespace
+        let allKeys = Array(defaults.dictionaryRepresentation().keys)
+        let namespaceKeys = allKeys.filter { $0.hasPrefix("\(namespace).") }
+        
+        // Remove from UserDefaults
+        for key in namespaceKeys {
+            defaults.removeObject(forKey: key)
+        }
+        
+        // Remove from iCloud
+        let allICloudKeys = Array(store.dictionaryRepresentation.keys)
+        let namespaceICloudKeys = allICloudKeys.filter { $0.hasPrefix("\(namespace).") }
+        
+        for key in namespaceICloudKeys {
+            store.removeObject(forKey: key)
+        }
+        
+        defaults.synchronize()
+        store.synchronize()
+    }
+    
+    /// Clears all disk data for a specific namespace.
+    ///
+    /// - Parameter namespace: The namespace to clear.
+    public static func clearDiskData(for namespace: String) {
+        let diskPath = PandoraDiskBoxPath.sharedRoot.appendingPathComponent(namespace)
+        try? FileManager.default.removeItem(at: diskPath)
+    }
+
+    /// Clears all disk cache data created by `Pandora.Disk` and `Pandora.Hybrid`.
     ///
     /// - Note: This is a destructive and irreversible operation.
     /// - Warning: This will delete **all** Pandora-managed disk caches.
     public static func clearAllDiskData() {
         try? FileManager.default.removeItem(at: PandoraDiskBoxPath.sharedRoot)
     }
 
-    /// Removes all keys from the standard `UserDefaults` and `NSUbiquitousKeyValueStore`.
-    ///
-    /// - Warning: This will clear **all keys**, not just Pandora-related ones.
-    public static func clearUserDefaults() {
+    /// Clears all UserDefaults and iCloud data for all Pandora namespaces.
+    public static func clearAllUserDefaults() {
         let defaults = Foundation.UserDefaults.standard
+        let store = NSUbiquitousKeyValueStore.default
+        
+        // Get all keys and filter by Pandora namespaces
+        let allKeys = Array(defaults.dictionaryRepresentation().keys)
+        let pandoraKeys = allKeys.filter { $0.hasPrefix("pandora.") }
 
-        for key in defaults.dictionaryRepresentation().keys {
+        // Remove from UserDefaults
+        for key in pandoraKeys {
             defaults.removeObject(forKey: key)
         }
 
-        let store = NSUbiquitousKeyValueStore.default
-
-        for key in store.dictionaryRepresentation.keys {
+        // Remove from iCloud
+        let allICloudKeys = Array(store.dictionaryRepresentation.keys)
+        let pandoraICloudKeys = allICloudKeys.filter { $0.hasPrefix("pandora.") }
+        
+        for key in pandoraICloudKeys {
             store.removeObject(forKey: key)
         }
 
         defaults.synchronize()
         store.synchronize()
-
     }
 
     /// Deletes all local and iCloud-backed data for this app:
@@ -355,7 +396,7 @@ public enum Pandora {
     /// - Warning: This will clear **all keys**, not just Pandora-related ones.
     public static func deleteAllLocalStorage() {
         clearAllDiskData()
-        clearUserDefaults()
+        clearAllUserDefaults()
     }
 
 }

Sources/Pandora/UserDefaultsBox/PandoraUserDefaultsBox.swift

@@ -115,17 +115,13 @@ public final class PandoraUserDefaultsBox<Value: Codable & Sendable>: PandoraDef
     // MARK: - Publisher
 
     /// Returns a publisher that emits the current and future values for the specified key.
-    public func publisher(for key: String, emitInitial: Bool = true) -> AnyPublisher<Value?, Never> {
-        if emitInitial {
-            let currentValue = syncLock.withLock { memory.get(key) }
-            return Publishers.Merge(
-                Just(currentValue).eraseToAnyPublisher(),
-                memory.publisher(for: key, emitInitial: false)
-            )
-            .eraseToAnyPublisher()
-        } else {
-            return memory.publisher(for: key, emitInitial: false)
-        }
+    public func publisher(for key: String) -> AnyPublisher<Value?, Never> {
+        let currentValue = syncLock.withLock { memory.get(key) }
+        return Publishers.Merge(
+            Just(currentValue).eraseToAnyPublisher(),
+            memory.publisher(for: key).dropFirst()
+        )
+        .eraseToAnyPublisher()
     }
 
     // MARK: - Get
@@ -243,7 +239,7 @@ public final class PandoraUserDefaultsBox<Value: Codable & Sendable>: PandoraDef
     // MARK: - Clear
 
     /// Removes all keys in the current namespace from all storage layers.
-    public func clear() {
+    public func clear() async {
         let prefix = "\(namespace)."
 
         syncLock.withLock {

Sources/Pandora/UserDefaultsBox/PandoraUserDefaultsBoxProtocol.swift

@@ -20,8 +20,7 @@ public protocol PandoraDefaultsBoxProtocol {
     /// Emits the current and future values for the given key.
     /// - Parameters:
     ///   - key: The cache key to observe.
-    ///   - emitInitial: Whether to emit the current value immediately upon subscription. Defaults to `true`.
-    func publisher(for key: String, emitInitial: Bool) -> AnyPublisher<Value?, Never>
+    func publisher(for key: String) -> AnyPublisher<Value?, Never>
 
     /// Reads the value for the given key, checking memory first, then UserDefaults,
     /// and iCloud if enabled.
@@ -37,7 +36,6 @@ public protocol PandoraDefaultsBoxProtocol {
 
     /// Clears all values in the current namespace from memory, UserDefaults,
     /// and iCloud if enabled.
-    func clear()
+    func clear() async
 }
 
-