update

Author: swiftuiux

Sources/d3-async-location/enum/Strategy.swift

@@ -0,0 +1,65 @@
+//
+//  Strategy.swift
+//  
+//
+//  Created by Igor Shelopaev on 10.02.2023.
+//
+
+import Foundation
+
+/// A protocol that defines a strategy for processing location results.
+/// Implementations of this protocol determine how new location results are handled
+/// (e.g., whether they replace the previous results or are appended).
+@available(iOS 14.0, watchOS 7.0, *)
+public protocol LocationResultStrategy {
+    
+    /// The type of output that the strategy processes.
+    /// `Output` is defined as `LocationStreamer.Output`, which is a `Result` containing
+    /// an array of `CLLocation` objects or a `CLError`.
+    typealias Output = LocationStreamer.Output
+    
+    /// Processes the results array by incorporating a new location result.
+    /// - Parameters:
+    ///   - results: The current array of processed results.
+    ///   - newResult: The new result to be processed and added.
+    /// - Returns: A new array of results after applying the strategy.
+    func process(results: [Output], newResult: Output) -> [Output]
+}
+
+/// A concrete strategy that keeps only the last location result.
+/// This strategy ensures that only the most recent location update is retained.
+@available(iOS 14.0, watchOS 7.0, *)
+public struct KeepLastStrategy: LocationResultStrategy {
+    
+    /// Initializes a new instance of `KeepLastStrategy`.
+    public init() {}
+    
+    /// Processes the results array by replacing it with the new result.
+    /// - Parameters:
+    ///   - results: The current array of processed results (ignored in this strategy).
+    ///   - newResult: The new result to be stored.
+    /// - Returns: An array containing only the new result.
+    public func process(results: [Output], newResult: Output) -> [Output] {
+        return [newResult]
+    }
+}
+
+/// A concrete strategy that keeps all location results.
+/// This strategy appends each new location result to the existing array.
+@available(iOS 14.0, watchOS 7.0, *)
+public struct KeepAllStrategy: LocationResultStrategy {
+    
+    /// Initializes a new instance of `KeepAllStrategy`.
+    public init() {}
+    
+    /// Processes the results array by appending the new result to it.
+    /// - Parameters:
+    ///   - results: The current array of processed results.
+    ///   - newResult: The new result to be added to the array.
+    /// - Returns: A new array of results, including the new result appended to the existing results.
+    public func process(results: [Output], newResult: Output) -> [Output] {
+        var updatedResults = results
+        updatedResults.append(newResult)
+        return updatedResults
+    }
+}

Sources/d3-async-location/helper/LocationResultStrategy.swift

@@ -10,16 +10,16 @@ import SwiftUI
 
 @available(iOS 14.0, watchOS 7.0, *)
 @MainActor
-public protocol ILocationManagerViewModel{
+public protocol ILocationStreamer{
 
     /// List of locations
     var results : [LocationStreamer.Output] { get }
 
     /// Strategy for publishing locations Default value is .keepLast
-    var strategy : LocationStreamer.Strategy { get }
+    var strategy : LocationResultStrategy { get }
 
     /// Start streaming locations
-    func start() async throws
+    func start(clean: Bool) async throws
 
     /// Stop streaming locations
     func stop()

Sources/d3-async-location/protocol/ILocationManagerViewModel.swift renamed to Sources/d3-async-location/protocol/ILocationStreamer.swift

@@ -8,55 +8,63 @@
 import SwiftUI
 import CoreLocation
 
-/// ViewModel for asynchronously posting location updates.
-/// Add or inject `LocationStreamer` into a View:
+/// A ViewModel for asynchronously streaming location updates.
+/// This class leverages `ObservableObject` to publish updates for SwiftUI Views.
+///
+/// Example usage in a View:
 /// ```
 /// @EnvironmentObject var model: LocationStreamer
 /// ```
-/// Use the `start()` method within an async environment to start an asynchronous stream of updates.
+///
+/// To start streaming updates, call the `start()` method within an async environment.
+///
+/// - Available: iOS 14.0+, watchOS 7.0+
 @available(iOS 14.0, watchOS 7.0, *)
-public final class LocationStreamer: ILocationManagerViewModel, ObservableObject{
+public final class LocationStreamer: ILocationStreamer, ObservableObject {
 
     /// Represents the output of the location manager.
-    /// Contains either a list of results (e.g., `CLLocation` objects) or a `CLError` in case of failure.
+    /// Each output is either:
+    /// - A list of results (`[CLLocation]` objects), or
+    /// - A `CLError` in case of failure.
     public typealias Output = Result<[CLLocation], CLError>
 
     // MARK: - Public Properties
 
-    /// Strategy for publishing updates. Default value is `.keepLast`.
-    public let strategy: Strategy
+    /// Defines the strategy for processing and publishing location updates.
+    /// Default strategy retains only the most recent update (`KeepLastStrategy`).
+    public let strategy: LocationResultStrategy
 
-    /// A list of results published for subscribed Views.
-    /// Results may include various types of data (e.g., `CLLocation` objects) depending on the implementation.
-    /// Use this publisher to feed Views with updates or create a proxy to manipulate the flow,
-    /// such as filtering, mapping, or dropping results.
+    /// A list of location results, published for subscribing Views.
+    /// This property is updated based on the chosen `strategy`.
     @MainActor @Published public private(set) var results: [Output] = []
 
-    /// Current streaming state of the ViewModel.
+    /// Indicates the current streaming state of the ViewModel.
+    /// State transitions include `.idle`, `.streaming`, and `.error`.
     @MainActor @Published public private(set) var state: LocationStreamingState = .idle
 
     // MARK: - Private Properties
 
-    /// The asynchronous locations manager responsible for streaming updates.
+    /// Handles the actual location updates asynchronously.
     private let manager: LocationManagerAsync
 
-    /// Indicates whether the streaming process is idle.
+    /// Checks if the streaming process is idle.
+    /// A computed property for convenience.
     @MainActor
     public var isIdle: Bool {
         return state == .idle
     }
 
     // MARK: - Lifecycle
 
-    /// Initializes the `LocationStreamer`.
+    /// Initializes the `LocationStreamer` with configurable parameters.
     /// - Parameters:
-    ///   - strategy: Strategy for publishing updates. Default value is `.keepLast`.
-    ///   - accuracy: The accuracy of geographical coordinates.
-    ///   - activityType: The type of activity associated with location updates.
-    ///   - distanceFilter: The minimum distance (in meters) that the device must move before an update event is generated. kCLDistanceFilterNone (equivalent to -1.0) means updates are sent regardless of the distance traveled. This is a safe default for apps that don’t require filtering updates based on distance.
-    ///   - backgroundUpdates: Indicates whether the app receives location updates when running in the background.
+    ///   - strategy: A `LocationResultStrategy` for managing location results. Defaults to `KeepLastStrategy`.
+    ///   - accuracy: Specifies the desired accuracy of location updates. Defaults to `kCLLocationAccuracyBest`.
+    ///   - activityType: The type of activity for location updates (e.g., automotive, fitness). Defaults to `.other`.
+    ///   - distanceFilter: The minimum distance (in meters) before generating an update. Defaults to `kCLDistanceFilterNone` (no filtering).
+    ///   - backgroundUpdates: Whether the app should continue receiving location updates in the background. Defaults to `false`.
     public init(
-        strategy: Strategy = .keepLast,
+        strategy: LocationResultStrategy = KeepLastStrategy(),
         _ accuracy: CLLocationAccuracy? = kCLLocationAccuracyBest,
         _ activityType: CLActivityType? = .other,
         _ distanceFilter: CLLocationDistance? = kCLDistanceFilterNone,
@@ -66,18 +74,19 @@ public final class LocationStreamer: ILocationManagerViewModel, ObservableObject
         manager = .init(accuracy, activityType, distanceFilter, backgroundUpdates)
     }
 
-    /// Initializes the `LocationManagerAsync` instance with a specified publishing strategy and `CLLocationManager`.
+    /// Initializes the `LocationStreamer` with a pre-configured `CLLocationManager`.
     /// - Parameters:
-    ///   - strategy: The strategy for publishing location updates. Defaults to `.keepLast`, which retains only the most recent update.
-    ///   - locationManager: A pre-configured `CLLocationManager` instance used to manage location updates.
+    ///   - strategy: A `LocationResultStrategy` for managing location results. Defaults to `KeepLastStrategy`.
+    ///   - locationManager: A pre-configured `CLLocationManager` instance.
     public init(
-        strategy: Strategy = .keepLast,
+        strategy: LocationResultStrategy = KeepLastStrategy(),
         locationManager: CLLocationManager
     ) {
         self.strategy = strategy
         manager = .init(locationManager: locationManager)
     }
 
+    /// Cleans up resources when the instance is deallocated.
     deinit {
         #if DEBUG
         print("deinit LocationStreamer")
@@ -86,14 +95,14 @@ public final class LocationStreamer: ILocationManagerViewModel, ObservableObject
 
     // MARK: - API
 
-    /// Starts streaming updates asynchronously.
+    /// Starts streaming location updates asynchronously.
+    /// - Parameters:
+    ///   - clean: Whether to clear previous results before starting. Defaults to `true`.
     /// - Throws: `AsyncLocationErrors.streamingProcessHasAlreadyStarted` if streaming is already active.
-    @MainActor public func start() async throws {
-        if state == .streaming {
-            stop()
-        }
+    @MainActor public func start(clean: Bool = true) async throws {
+        if state == .streaming { stop() }
+        if clean { self.clean() }
 
-        clean()
         setState(.streaming)
 
         let stream = try await manager.start()
@@ -104,7 +113,7 @@ public final class LocationStreamer: ILocationManagerViewModel, ObservableObject
         setState(.idle)
     }
 
-    /// Stops the streaming process and resets the state to idle.
+    /// Stops the location streaming process and sets the state to idle.
     @MainActor public func stop() {
         manager.stop()
         setState(.idle)
@@ -116,25 +125,22 @@ public final class LocationStreamer: ILocationManagerViewModel, ObservableObject
 
     // MARK: - Private Methods
 
+    /// Clears all stored results.
     @MainActor
-    private func clean(){
+    private func clean() {
         results = []
     }
 
-    /// Adds a new result to the `results` array based on the publishing strategy.
-    /// - Parameter result: The new result to be added.
+    /// Adds a new location result to the `results` array.
+    /// The behavior depends on the configured `strategy`.
+    /// - Parameter result: The new result to be processed and added.
     @MainActor
     private func add(_ result: Output) {
-        switch strategy {
-        case .keepAll:
-            results.append(result)
-        case .keepLast:
-            results = [result]
-        }
+        results = strategy.process(results: results, newResult: result)
     }
 
-    /// Updates the current state of the ViewModel.
-    /// - Parameter value: The new streaming state to set.
+    /// Updates the streaming state of the ViewModel.
+    /// - Parameter value: The new state to set (e.g., `.idle`, `.streaming`).
     @MainActor
     private func setState(_ value: LocationStreamingState) {
         state = value