composable-core-location

Introduction to Composable Core Location

Composable Core Location is a powerful library designed to seamlessly integrate the Composable Architecture with Core Location in iOS applications. This library offers a structured approach to handling location-based functionalities, empowering developers to build sophisticated, testable applications efficiently.

Example

The library comes with an excellent example in the form of the LocationManager demo. This demo showcases how Composable Core Location operates in a practical scenario, providing a reference point for developers.

Basic Usage

To start using Composable Core Location, developers will typically follow a series of steps:

1. Action Integration: Developers need to integrate an action into their domain that represents the actions emitted by the CLLocationManagerDelegate methods. This is done using the LocationManager.Action enum, which covers various delegate methods like didUpdateLocations and didEnterRegion.

   import ComposableCoreLocation
   
   enum AppAction {
     case locationManager(LocationManager.Action)
     // Other actions specific to your domain
   }
   

2. Environment Setup: A LocationManager instance, provided by the library, is added to the application's environment of dependencies.

   struct AppEnvironment {
     var locationManager: LocationManager
     // Other domain-specific dependencies
   }
   

3. Subscription and Authorization: By returning an effect from an action—such as onAppear—the app subscribes to delegate actions and requests authorization.

   let appReducer = Reducer<AppState, AppAction, AppEnvironment> { state, action, environment in
     switch action {
     case .onAppear:
       return .merge(
         environment.locationManager.delegate().map(AppAction.locationManager),
         environment.locationManager.requestWhenInUseAuthorization().fireAndForget()
       )
     }
   }
   

4. Handling Delegate Actions: Developers handle specific actions such as location authorization or updates. This allows for the implementation of features like requesting user location or showing an alert when access is denied.

   case .locationManager(.didChangeAuthorization(.authorizedAlways)),
        .locationManager(.didChangeAuthorization(.authorizedWhenInUse)):
     return environment.locationManager.requestLocation().fireAndForget()
   
   case .locationManager(.didChangeAuthorization(.denied)),
        .locationManager(.didChangeAuthorization(.restricted)):
     state.alert = "Please give location access so that we can show you some cool stuff."
     return .none
   

5. Creating the Store: The "live" implementation of LocationManager is fed into the Store, which powers the application.

   let store = Store(
     initialState: AppState(),
     reducer: appReducer,
     environment: AppEnvironment(
       locationManager: .live
     )
   )
   

This comprehensive approach allows developers to easily integrate location services into their applications.

Testing

One of the significant strengths of Composable Core Location is its ability to facilitate thorough testing. Developers can create a TestStore with a .failing version of the LocationManager, allowing them to simulate and test various scenarios like authorization requests and denied access straightforwardly.

For instance, asserting sequence of events like appearing on screen, denying access, and verifying alert displays is made simple and systematic. This robust testing capability ensures applications are reliable and bug-free.

Installation

Adding Composable Core Location to your Xcode project is straightforward:

1. Open the File menu and choose Swift Packages › Add Package Dependency…
2. Enter the URL: https://github.com/pointfreeco/composable-core-location.

This process integrates the library into your project, ready for use.

Documentation

Developers looking for in-depth understanding can find comprehensive documentation here.

Help and Community

The community around Composable Core Location is active. For discussions or questions on usage, developers are encouraged to visit its Swift forum.

Composable Core Location is open source, released under the MIT license, aligning with the modern open-source mantra of collaboration and shared knowledge. This project empowers developers to build and test applications with rich location-based features seamlessly.