AsyncLocationKit

AsyncLocationKit uses a Performer Pattern to wrap Apple's delegate-based CoreLocation API into a modern async/await interface.

• AsyncLocationManager: The public API entry point.
• AsyncDelegateProxy: A thread-safe dispatcher that routes CoreLocation delegate events to the appropriate performers.
• Performers: Specialized handlers (e.g., SingleLocationUpdatePerformer, AuthorizationPerformer) that implement specific logic for different CoreLocation tasks.
• Events: Strongly-typed enums that represent the actual data or errors received from CoreLocation.

To use AsyncLocationKit in your Swift project, add it as a dependency in your Package.swift file or via Xcode's Package Dependency interface.

Swift Package Manager (Package.swift):

dependencies: [
    .package(url: "https://github.com/AsyncSwift/AsyncLocationKit.git", from: "2.0.1")
]

Xcode:

1. Go to File → Add Package Dependencies.
2. Enter the URL: https://github.com/AsyncSwift/AsyncLocationKit.git.
3. Select version 2.0.1 or later.

If you are moving from a traditional CLLocationManagerDelegate pattern to AsyncLocationKit, you can replace delegate callbacks with async/await calls. Instead of implementing locationManager(_:didUpdateLocations:), you can use requestLocation() to await a single location event.

let locationManager = AsyncLocationManager()

do {
    if let event = try await locationManager.requestLocation() {
        if case .didUpdateLocations(let locations) = event {
            print(locations.first)
        }
    }
} catch {
    print("Error: \(error)")
}

Add AsyncLocationKit to your Podfile and run pod install to integrate it into your project.

pod 'AsyncLocationKit', :git => 'https://github.com/AsyncSwift/AsyncLocationKit.git', :tag => '2.0.1'

Follow these guidelines to ensure stability and battery efficiency:

1. Initialize on the main thread: AsyncLocationManager must be initialized on the main thread to satisfy CoreLocation requirements.
2. Check authorization first: Always verify permission status using requestPermission(with:) before attempting to request locations.
3. Cancel tasks to stop updates: Continuous location updates are provided via streams. To stop monitoring, simply cancel the Task that is iterating over the stream.
4. Optimize accuracy: Use lower accuracy settings (e.g., .hundredMetersAccuracy) when high precision is not required to conserve battery.
5. Configure Info.plist: You must include the required location usage description keys in your app's Info.plist.

The AsyncLocationManager is the main entry point for the library.

Important: Always initialize AsyncLocationManager synchronously on the main thread.

import AsyncLocationKit

let locationManager = AsyncLocationManager(desiredAccuracy: .bestAccuracy)

You can set the initial accuracy and background update capabilities during initialization, or update them dynamically.

Accuracy Levels:

• .bestAccuracy
• .nearestTenMetersAccuracy
• .hundredMetersAccuracy
• .kilometerAccuracy
• .threeKilometersAccuracy
• .bestForNavigationAccuracy

Background Updates: Supported on iOS, macOS, and watchOS. Use allowsBackgroundLocationUpdates to enable/disable.

// Initialization
let manager = AsyncLocationManager(
    desiredAccuracy: .bestAccuracy,
    allowsBackgroundLocationUpdates: true
)

// Dynamic updates
manager.updateAccuracy(with: .hundredMetersAccuracy)

#if !os(tvOS)
manager.updateAllowsBackgroundLocationUpdates(with: true)
#endif

Location updates not working

• Verify Info.plist keys are present.
• Ensure authorization has been granted.
• Check if location services are enabled on the device.
• Confirm AsyncLocationManager was initialized on the main thread.

Background location not working

• Add "Location updates" to Background Modes in your Xcode project capabilities.
• Set allowsBackgroundLocationUpdates to true.
• Request .whenInUse or .always authorization (ensure you request 'Always' if background access is required).

Task cancelled warning

• This is expected behavior when a Task monitoring location updates is cancelled; the library handles resource cleanup automatically.

Use startUpdatingLocation() to receive a continuous stream of location events via an AsyncStream. You can iterate over this stream using a for await loop.

Note: The stream automatically stops when the parent Task is cancelled.

Task {
    for await event in await locationManager.startUpdatingLocation() {
        switch event {
        case .didUpdateLocations(let locations):
            print("New location: \(locations.last?.coordinate)")
        case .didFailWith(let error):
            print("Error: \(error)")
        case .didPaused:
            print("Location updates paused")
        case .didResume:
            print("Location updates resumed")
        }
    }
}

// To stop updates, cancel the task:
// task.cancel()

Use requestPermission(with:) to prompt the user for location access. You can request either .whenInUsage or .always permissions.

The method returns a CLAuthorizationStatus which you can use to handle the user's response.

// Request "When In Use" authorization
let status = await locationManager.requestPermission(with: .whenInUsage)

// Or request "Always" authorization
let status = await locationManager.requestPermission(with: .always)

// Handle the authorization status
switch status {
case .authorizedWhenInUse, .authorizedAlways:
    print("Location authorized!")
case .denied:
    print("Location access denied")
case .restricted:
    print("Location access restricted")
case .notDetermined:
    print("Authorization not determined")
@unknown default:
    print("Unknown authorization status")
}

To get the user's current location once, use requestLocation(). This method returns an optional LocationUpdateEvent? which contains either the updated locations or a failure error.

do {
    if let event = try await locationManager.requestLocation() {
        switch event {
        case .didUpdateLocations(let locations):
            print("Current location: \(locations.first?.coordinate)")
        case .didFailWith(let error):
            print("Location error: \(error)")
        default:
            break
        }
    }
} catch {
    print("Failed to get location: \(error)")
}