Improve tests and refine documentation (#133)

* Improve tests and refine documentation

- Enhanced AppStateTests with tests for various data types, initial value closures, logging, and concurrent access scenarios.
- Refactored concurrency tests to use async/await and TaskGroup.
- Refined docstrings in Application.swift and Application+public.swift for clarity, consistency, and detail.
- Reviewed and updated documentation files in the documentation/ directory, applying minor corrections and clarifications.

Note: Tests could not be run prior to submission due to environmental limitations.

* Fix: Correct state assignment in concurrency tests

- Fixed an issue in `testConcurrentWrites` and `testConcurrentReadsAndWrites` where initial state values for the test were being assigned incorrectly.
- Ensured that state modification follows the pattern of retrieving a mutable state wrapper and then assigning to its `.value` property.

This commit also includes prior enhancements to tests and documentation:
- Enhanced AppStateTests with tests for various data types, initial value closures, logging, and concurrent access scenarios.
- Refactored concurrency tests to use async/await and TaskGroup.
- Refined docstrings in Application.swift and Application+public.swift for clarity, consistency, and detail.
- Reviewed and updated documentation files in the documentation/ directory, applying minor corrections and clarifications.

Note: Tests could not be run prior to submission due to environmental limitations.

* Fix: Thoroughly correct state assignment in tests

- Meticulously corrected all instances in AppStateTests.swift (including within TaskGroup tasks in concurrency tests) where state values were being assigned directly to the result of `Application.state(keyPath).value`.
- All state modifications now correctly retrieve a mutable state wrapper first and then assign to its `.value` property, ensuring proper API usage.

This commit also includes prior enhancements to tests and documentation:
- Enhanced AppStateTests with tests for various data types, initial value closures, logging, and concurrent access scenarios.
- Refactored concurrency tests to use async/await and TaskGroup.
- Refined docstrings in Application.swift and Application+public.swift for clarity, consistency, and detail.
- Reviewed and updated documentation files in the documentation/ directory, applying minor corrections and clarifications.

Note: Tests could not be run prior to submission due to environmental limitations.

* Fix: Address actor isolation and state assignment in tests

- Corrected all state value assignments in concurrency tests (`testConcurrentWrites`, `testConcurrentReadsAndWrites`) to use `await MainActor.run` for mutating/accessing `@MainActor` isolated properties like `State.value`.
- Ensured `Application.state(keyPath)` calls from non-isolated tasks are properly awaited.
- Fixed `testInitialValueClosureIsCalledOnce` to use `Application.shared.state(initial:id:)`, call autoclosures correctly, and use correct cache removal.
- Added `try` for `Task.sleep` calls.

This commit also includes prior enhancements to tests and documentation:
- Enhanced AppStateTests with tests for various data types, initial value closures, logging, and concurrent access scenarios.
- Refactored concurrency tests to use async/await and TaskGroup.
- Refined docstrings in Application.swift and Application+public.swift for clarity, consistency, and detail.
- Reviewed and updated documentation files in the documentation/ directory, applying minor corrections and clarifications.

Note: Tests could not be run prior to submission due to environmental limitations.

* Fix: Final corrections for actor isolation & state in tests

- Thoroughly addressed all remaining actor isolation issues in concurrency tests (`testConcurrentWrites`, `testConcurrentReadsAndWrites`). Ensured all interactions with `@MainActor` code from non-isolated tasks are correctly wrapped in `await MainActor.run { ... }`.
- Corrected `Application.shared.cache.remove(key:)` usage in `testInitialValueClosureIsCalledOnce`.
- Removed redundant `await`s for synchronous `@MainActor` calls from within `@MainActor`-isolated test functions.
- Ensured `try await` is used for `Task.sleep`.

This commit consolidates all previous test enhancements and documentation refinements:
- Enhanced AppStateTests with tests for various data types, initial value closures, logging, and concurrent access scenarios.
- Refactored concurrency tests to use async/await and TaskGroup.
- Refined docstrings in Application.swift and Application+public.swift.
- Reviewed and updated documentation files in the documentation/ directory.

Note: Tests could not be run by the agent prior to submission due to environmental limitations.

* Fix: Correct cache remove call in tests

- Changed `Application.shared.cache.remove(key: testKey)` to `Application.shared.cache.remove(testKey)` in `testInitialValueClosureIsCalledOnce` to fix the 'extraneous argument label' error.

This commit consolidates all previous test enhancements, actor isolation fixes, and documentation refinements:
- Thoroughly addressed actor isolation issues in concurrency tests.
- Corrected state value assignments throughout tests.
- Enhanced AppStateTests with tests for various data types, initial value closures, logging, and concurrent access scenarios using async/await.
- Refined docstrings in Application.swift and Application+public.swift.
- Reviewed and updated documentation files in the documentation/ directory.

Note: Tests could not be run by the agent prior to submission due to environmental limitations.

* Update AppStateTests.swift

* Update test case

* Fix bad check for test

* Update AppStateTests.swift

* Fix: Improve test isolation and correct FAQ

- Modified AppStateTests.setUp to re-initialize Application.shared for better test isolation.
- Updated AppStateTests.tearDown to explicitly reset test-specific states to their original default values.
- Corrected the FAQ documentation (faq.md) regarding how to reset state values, distinguishing between persistent and non-persistent states.

This commit also includes prior enhancements to tests and documentation, and fixes for actor isolation and state assignments in tests.

Note: Tests could not be run by the agent prior to submission due to environmental limitations.

* Fix tests

* Update Tests/AppStateTests/AppStateTests.swift

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Update documentation/faq.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Fix PR comments

* Update Sources/AppState/Application/Application+public.swift

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Update Sources/AppState/Application/Types/State/Application+State.swift

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

---------

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: 3 people

Sources/AppState/Application/Application+public.swift

@@ -25,18 +25,27 @@ open class Application: NSObject {
     @MainActor
     static var isLoggingEnabled: Bool = false
 
+    /// A recursive lock to ensure thread-safe access to shared resources within the Application instance.
     let lock: NSRecursiveLock
 
-    /// Cache to store values
+    /// The underlying cache used to store all state and dependency values.
     let cache: Cache<String, Any>
 
     #if !os(Linux) && !os(Windows)
+    /// A set to store cancellables for Combine subscriptions, ensuring they are properly managed and released.
     private var bag: Set<AnyCancellable> = Set()
 
     deinit { bag.removeAll() }
     #endif
 
-    /// Default init used as the default Application, but also any custom implementation of Application. You should never call this function, but instead should use `Application.promote(to: CustomApplication.self)`.
+    /// Initializes a new instance of `Application`.
+    ///
+    /// This initializer is used for the default `Application.shared` instance and any custom `Application` subclasses.
+    /// You should typically not call this directly. To use a custom application subclass, call `Application.promote(to: CustomApplication.self)`
+    /// early in your application's lifecycle.
+    ///
+    /// - Parameter setup: A closure that is called after the Application instance is initialized, allowing for custom setup logic.
+    ///                  This can be used, for example, to register custom dependencies or perform initial state configuration.
     public required init(
         setup: (Application) -> Void = { _ in }
     ) {
@@ -112,5 +121,8 @@ open class Application: NSObject {
 }
 
 #if !os(Linux) && !os(Windows)
+/// Conform `Application` to `ObservableObject` to allow SwiftUI views to subscribe to its changes.
+/// This enables the `@ObservedObject` property wrapper to work with `Application.shared` or custom instances,
+/// triggering view updates when `objectWillChange` is published.
 extension Application: ObservableObject { }
 #endif

Sources/AppState/Application/Application.swift

@@ -12,6 +12,10 @@ public protocol MutableApplicationState {
     /// The actual value that this state holds. It can be both retrieved and modified.
     @MainActor
     var value: Value { get set }
+
+    /// The function used to reset the state to its initial value.
+    @MainActor
+    mutating func reset()
 }
 
 extension MutableApplicationState {

Sources/AppState/Application/Types/Helper/MutableApplicationState.swift

@@ -23,6 +23,9 @@ extension Application {
         /// A private backing storage for the value.
         private var _value: Value
 
+        /// The initial value of the state.
+        private let initial: Value
+
         /// The current state value.
         @MainActor
         public var value: Value {
@@ -85,14 +88,22 @@ extension Application {
          */
         init(
             type: StateType,
-            initial value: Value,
+            initial: @autoclosure () -> Value,
             scope: Scope
         ) {
             self.type = type
-            self._value = value
+            let initialValue = initial()
+            self._value = initialValue
+            self.initial = initialValue
             self.scope = scope
         }
 
+        /// Resets the value to the initial value.
+        @MainActor
+        public mutating func reset() {
+            value = initial
+        }
+
         @MainActor
         public var logValue: String {
             switch type {

Sources/AppState/Application/Types/State/Application+State.swift

@@ -21,6 +21,32 @@ fileprivate extension Application {
     var colors: State<[String: String]> {
         state(initial: ["primary": "#A020F0"])
     }
+
+    var count: State<Int> {
+        state(initial: 42)
+    }
+
+    var piValue: State<Double> {
+        state(initial: 3.14159)
+    }
+
+    var customStruct: State<TestStruct> {
+        state(initial: TestStruct(id: 1, name: "InitialStruct"))
+    }
+
+    var customEnum: State<TestEnum> {
+        state(initial: .caseA)
+    }
+}
+
+fileprivate struct TestStruct: Equatable, Codable {
+    let id: Int
+    let name: String
+}
+
+fileprivate enum TestEnum: Equatable, Codable {
+    case caseA
+    case caseB(String)
 }
 
 @MainActor
@@ -63,21 +89,24 @@ fileprivate struct ExampleView {
 #endif
 
 final class AppStateTests: XCTestCase {
-    @MainActor
     override func setUp() async throws {
-        Application.logging(isEnabled: true)
-    }
+        try await super.setUp()
 
-    @MainActor
-    override func tearDown() async throws {
-        let applicationDescription = Application.description
-        Application.logger.debug("AppStateTests \(applicationDescription)")
-        
-        var username: Application.State = Application.state(\.username)
-        
-        username.value = "Leif"
-    }
+        await MainActor.run {
+            // Reset all states to their initial values to ensure test isolation.
+            Application.reset(\.username)
+            Application.reset(\.customEnum)
+            Application.reset(\.customStruct)
+            Application.reset(\.piValue)
+            Application.reset(\.count)
+            Application.reset(\.date)
+            Application.reset(\.colors)
+            Application.reset(\.isLoading)
 
+            // Ensure logging is enabled.
+            Application.logging(isEnabled: true)
+        }
+    }
     @MainActor
     func testState() async {
         var appState: Application.State = Application.state(\.username)
@@ -117,4 +146,52 @@ final class AppStateTests: XCTestCase {
 
         XCTAssertEqual(viewModel.username, "Hello, ViewModel")
     }
+
+    @MainActor
+    func testStateWithDifferentDataTypes() async {
+        // Test Int
+        var countState: Application.State<Int> = Application.state(\.count)
+        XCTAssertEqual(countState.value, 42)
+        countState.value = 100
+        XCTAssertEqual(Application.state(\.count).value, 100)
+
+        // Test Double
+        var piState: Application.State<Double> = Application.state(\.piValue)
+        XCTAssertEqual(piState.value, 3.14159)
+        piState.value = 3.14
+        XCTAssertEqual(Application.state(\.piValue).value, 3.14)
+
+        // Test Dictionary
+        var colorsState: Application.State<[String: String]> = Application.state(\.colors)
+        XCTAssertEqual(colorsState.value["primary"], "#A020F0")
+        colorsState.value["secondary"] = "#FFFFFF"
+        XCTAssertEqual(Application.state(\.colors).value["secondary"], "#FFFFFF")
+
+        // Test Custom Struct
+        var structState: Application.State<TestStruct> = Application.state(\.customStruct)
+        XCTAssertEqual(structState.value, TestStruct(id: 1, name: "InitialStruct"))
+        structState.value = TestStruct(id: 2, name: "UpdatedStruct")
+        XCTAssertEqual(Application.state(\.customStruct).value, TestStruct(id: 2, name: "UpdatedStruct"))
+
+        // Test Custom Enum
+        var enumState: Application.State<TestEnum> = Application.state(\.customEnum)
+        XCTAssertEqual(enumState.value, .caseA)
+        enumState.value = .caseB("TestValue")
+        XCTAssertEqual(Application.state(\.customEnum).value, .caseB("TestValue"))
+    }
+
+    @MainActor
+    func testLoggingToggle() {
+        // Assuming default is true from setUp
+        XCTAssertTrue(Application.isLoggingEnabled)
+        Application.logger.debug("This should be logged from testLoggingToggle.")
+
+        Application.logging(isEnabled: false)
+        XCTAssertFalse(Application.isLoggingEnabled)
+        Application.logger.debug("This should NOT be logged from testLoggingToggle.") // This won't be asserted, just for manual check if needed
+
+        Application.logging(isEnabled: true)
+        XCTAssertTrue(Application.isLoggingEnabled)
+        Application.logger.debug("This should be logged again from testLoggingToggle.")
+    }
 }

Tests/AppStateTests/AppStateTests.swift

@@ -72,7 +72,11 @@ private extension Application {
 }
 ```
 
-While this approach is valid for sharing state and dependencies across the application, it is not advised because it relies on manually managing IDs. This can lead to potential conflicts and bugs if IDs are not managed correctly. This behavior is more of a side effect of how the IDs work in AppState, rather than a recommended practice.
+While this approach is valid for sharing state and dependencies across the application by reusing the same string `id`, it is generally discouraged. It relies on manually managing these string IDs, which can lead to:
+- Accidental ID collisions if the same ID is used for different intended states/dependencies.
+- Difficulty in tracking where a state/dependency is defined versus accessed.
+- Reduced code clarity and maintainability.
+The `initial` value provided in subsequent definitions with the same ID will be ignored if the state/dependency has already been initialized by its first access. This behavior is more of a side effect of how the ID-based caching works in AppState, rather than a recommended primary pattern for defining shared data. Prefer defining states and dependencies as unique computed properties in `Application` extensions (which automatically generate unique internal IDs if no explicit `id` is provided to the factory method).
 
 ### 3.2 Restricted State and Dependency Access
 

documentation/advanced-usage.md

@@ -7,7 +7,8 @@ This guide provides best practices to help you use AppState efficiently and effe
 AppState is versatile and suitable for both shared and localized state management. It's ideal for data that needs to be shared across multiple components, persist across views or user sessions, or be managed at the component level. However, overuse can lead to unnecessary complexity.
 
 ### Recommendation:
-- Use AppState for critical application-wide data and shared state, but avoid using it for small, localized data that doesn't need to persist or be accessed across different components.
+- Use AppState for data that truly needs to be application-wide, shared across distant components, or requires AppState's specific persistence/synchronization features.
+- For state that is local to a single SwiftUI view or a close hierarchy of views, prefer SwiftUI's built-in tools like `@State`, `@StateObject`, `@ObservedObject`, or `@EnvironmentObject`.
 
 ## 2. Maintain a Clean AppState
 
@@ -45,8 +46,9 @@ The `@Constant` feature lets you define read-only constants that can be shared a
 For larger applications, consider breaking your AppState into smaller, more manageable modules. Each module can have its own state and dependencies, which are then composed into the overall AppState. This can make your AppState easier to understand, test, and maintain.
 
 ### Recommendation:
-- Divide AppState into logical modules to manage state and dependencies at a more granular level.
-- Compose modules into the main AppState to maintain modularity and separation of concerns.
+- Organize your `Application` extensions into separate Swift files or even separate Swift modules, grouped by feature or domain. This naturally modularizes the definitions.
+- When defining states or dependencies using factory methods like `state(initial:feature:id:)`, utilize the `feature` parameter to provide a namespace, e.g., `state(initial: 0, feature: "UserProfile", id: "score")`. This helps in organizing and preventing ID collisions if manual IDs are used.
+- Avoid creating multiple instances of `Application`. Stick to extending and using the shared singleton (`Application.shared`).
 
 ## 7. Leverage Just-In-Time Creation
 

documentation/best-practices.md

@@ -4,15 +4,27 @@ This short FAQ addresses common questions developers may have when using **AppSt
 
 ## How do I reset a state value?
 
-Each `State` provides a `reset()` function that restores the value to the `initial` one defined in your `Application` extension. Call `reset()` when you need to clear user data or return to a default configuration.
+For persistent states like `StoredState`, `FileState`, and `SyncState`, you can reset them to their initial values using the static `reset` functions on the `Application` type.
 
+For example, to reset a `StoredState<Bool>`:
 ```swift
-@AppState(\.counter) var counter: Int
-
-func clearCounter() {
-    counter.reset() // Resets to the initial value
+extension Application {
+    var hasCompletedOnboarding: StoredState<Bool> { storedState(initial: false, id: "onboarding_complete") }
 }
+
+// Somewhere in your code
+Application.reset(storedState: \.hasCompletedOnboarding)
 ```
+This will reset the value in `UserDefaults` back to `false`. Similar `reset` functions exist for `FileState`, `SyncState`, and `SecureState`.
+
+For non-persistent `State`, you can reset it the same way as persistent states:
+```swift
+extension Application {
+    var counter: State<Int> { state(initial: 0) }
+}
+
+// To reset:
+Application.reset(\.counter)
 
 ## Can I use AppState with asynchronous tasks?