Modern, async/await wrapper for Apple's CoreLocation framework
No more delegate patterns or completion blocks. Embrace Swift's structured concurrency.
- Async/Await Native: Built from the ground up for Swift's modern concurrency model
- AsyncStream Support: Monitor continuous location updates with
for awaitloops - Type-Safe: Comprehensive event types for all CoreLocation scenarios
- Zero Dependencies: Pure Swift, no external frameworks
- Multi-Platform: iOS, macOS, watchOS, and tvOS support
- Thread-Safe: Concurrent access protected with serial dispatch queues
- Swift 6 Ready: Full Sendable conformance for strict concurrency checking
Add AsyncLocationKit to your Package.swift:
dependencies: [
.package(url: "https://github.com/AsyncSwift/AsyncLocationKit.git", from: "2.0.0")
]Or add it directly in Xcode:
- File β Add Package Dependencies
- Enter:
https://github.com/AsyncSwift/AsyncLocationKit.git - Select version
2.0.0or later
Add to your Podfile:
pod 'AsyncLocationKit', :git => 'https://github.com/AsyncSwift/AsyncLocationKit.git', :tag => '2.0.0'Then run:
pod installImportant: Always initialize
AsyncLocationManagersynchronously on the main thread.
import AsyncLocationKit
let locationManager = AsyncLocationManager(desiredAccuracy: .bestAccuracy)// 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")
}Get the user's location once:
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)")
}Monitor location changes using AsyncStream:
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")
}
}
}The stream automatically stops when the Task is cancelled:
let task = Task {
for await event in await locationManager.startUpdatingLocation() {
// Handle location updates
}
}
// Later, cancel the task to stop location updates
task.cancel()Task {
for await event in await locationManager.startMonitoringAuthorization() {
switch event {
case .didUpdate(let authorization):
print("Authorization changed to: \(authorization)")
}
}
}Task {
for await event in await locationManager.startMonitoringLocationEnabled() {
switch event {
case .didUpdate(let enabled):
print("Location services enabled: \(enabled)")
}
}
}let region = CLCircularRegion(
center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194),
radius: 100,
identifier: "San Francisco"
)
Task {
for await event in await locationManager.startMonitoring(for: region) {
switch event {
case .didEnterTo(let region):
print("Entered region: \(region.identifier)")
case .didExitTo(let region):
print("Exited region: \(region.identifier)")
case .didStartMonitoringFor(let region):
print("Started monitoring: \(region.identifier)")
case .monitoringDidFailFor(let region, let error):
print("Monitoring failed: \(error)")
}
}
}#if os(iOS)
Task {
for await event in await locationManager.startUpdatingHeading() {
switch event {
case .didUpdate(let heading):
print("Heading: \(heading.trueHeading)Β°")
case .didFailWith(let error):
print("Heading error: \(error)")
}
}
}
#endif#if os(iOS)
Task {
for await event in await locationManager.startMonitoringVisit() {
switch event {
case .didVisit(let visit):
print("Visit: \(visit.coordinate)")
print("Arrival: \(visit.arrivalDate)")
print("Departure: \(visit.departureDate)")
case .didFailWithError(let error):
print("Visit monitoring error: \(error)")
}
}
}
#endif#if !os(watchOS) && !os(tvOS)
let beaconConstraint = CLBeaconIdentityConstraint(
uuid: UUID(uuidString: "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0")!
)
Task {
for await event in await locationManager.startRangingBeacons(satisfying: beaconConstraint) {
switch event {
case .didRange(let beacons, _):
print("Found \(beacons.count) beacons")
case .didFailRanginFor(_, let error):
print("Beacon ranging failed: \(error)")
}
}
}
#endif#if !os(watchOS) && !os(tvOS)
Task {
for await event in await locationManager.startMonitoringSignificantLocationChanges() {
switch event {
case .didUpdateLocations(let locations):
print("Significant location change: \(locations)")
case .didFailWith(let error):
print("Error: \(error)")
case .didPaused, .didResume:
break
}
}
}
#endif#if os(iOS)
if #available(iOS 14.0, *) {
do {
let accuracy = try await locationManager.requestTemporaryFullAccuracyAuthorization(
purposeKey: "YourPurposeKeyFromInfoPlist"
)
print("Accuracy authorization: \(accuracy)")
} catch {
print("Failed to request full accuracy: \(error)")
}
}
#endifAsyncLocationKit uses a Performer Pattern to elegantly manage the complex delegate-based CoreLocation API:
βββββββββββββββββββββββββββ
β AsyncLocationManager β
β (Public API) β
βββββββββββββ¬ββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββ
β AsyncDelegateProxy β
β (Event Dispatcher) β
βββββββββββββ¬ββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββ
β AnyLocationPerformer β
β (Protocol) β
βββββββββββββ¬ββββββββββββββ
β
ββββΊ SingleLocationUpdatePerformer
ββββΊ MonitoringUpdateLocationPerformer
ββββΊ AuthorizationPerformer
ββββΊ RegionMonitoringPerformer
ββββΊ ...and more
Key Components:
- AsyncLocationManager: Main entry point providing async/await methods
- AsyncDelegateProxy: Thread-safe dispatcher routing events to performers
- Performers: Individual handlers for specific CoreLocation delegate methods
- Events: Strongly-typed enums representing CoreLocation callbacks
This architecture provides:
- Thread-safe concurrent access
- Clean separation of concerns
- Easy testability
- Type safety throughout
let manager = AsyncLocationManager(desiredAccuracy: .bestAccuracy)
// Available accuracy levels:
// .bestAccuracy
// .nearestTenMetersAccuracy
// .hundredMetersAccuracy
// .kilometerAccuracy
// .threeKilometersAccuracy
// .bestForNavigationAccuracy
// Update accuracy dynamically:
manager.updateAccuracy(with: .hundredMetersAccuracy)let manager = AsyncLocationManager(
desiredAccuracy: .bestAccuracy,
allowsBackgroundLocationUpdates: true
)
// Update background setting dynamically (iOS/macOS/watchOS only):
#if !os(tvOS)
manager.updateAllowsBackgroundLocationUpdates(with: true)
#endif| Method | Description | Return Type |
|---|---|---|
requestPermission(with:) |
Request location permission | CLAuthorizationStatus |
getAuthorizationStatus() |
Get current authorization status | CLAuthorizationStatus |
startMonitoringAuthorization() |
Monitor authorization changes | AuthorizationStream |
| Method | Description | Return Type |
|---|---|---|
requestLocation() |
Request single location update | LocationUpdateEvent? |
startUpdatingLocation() |
Start continuous updates | LocationStream |
stopUpdatingLocation() |
Stop location updates | Void |
| Method | Description | Return Type |
|---|---|---|
startMonitoring(for:) |
Monitor region entry/exit | RegionMonitoringStream |
startMonitoringVisit() |
Monitor significant visits | VisitMonitoringStream |
startMonitoringSignificantLocationChanges() |
Monitor significant changes | SignificantLocationChangeMonitoringStream |
| Method | Description | Return Type |
|---|---|---|
getLocationEnabled() |
Check if location services enabled | Bool |
startMonitoringLocationEnabled() |
Monitor location services status | LocationEnabledStream |
| Feature | iOS | macOS | watchOS | tvOS |
|---|---|---|---|---|
| Basic Location | β | β | β | β |
| Authorization | β | β | β | β |
| Region Monitoring | β | β | β | β |
| Visit Monitoring | β | β | β | β |
| Heading Updates | β | β | β | β |
| Beacon Ranging | β | β | β | β |
| Significant Changes | β | β | β | β |
| Background Updates | β | β | β | β |
- Swift: 5.5 or later
- iOS: 13.0 or later
- macOS: 12.0 or later
- watchOS: 6.0 or later
- tvOS: 13.0 or later
- Xcode: 13.0 or later
Before (delegate pattern):
class LocationManager: NSObject, CLLocationManagerDelegate {
let manager = CLLocationManager()
var completion: ((CLLocation?) -> Void)?
override init() {
super.init()
manager.delegate = self
}
func requestLocation() {
manager.requestLocation()
}
func locationManager(_ manager: CLLocationManager,
didUpdateLocations locations: [CLLocation]) {
completion?(locations.first)
}
}After (async/await):
let locationManager = AsyncLocationManager()
do {
if let event = try await locationManager.requestLocation() {
if case .didUpdateLocations(let locations) = event {
print(locations.first)
}
}
} catch {
print("Error: \(error)")
}-
Always initialize on the main thread: CoreLocation requires main thread initialization
let manager = AsyncLocationManager() // β On main thread
-
Handle authorization properly: Always check authorization before requesting location
let status = await manager.requestPermission(with: .whenInUsage) guard status == .authorizedWhenInUse || status == .authorizedAlways else { return }
-
Cancel tasks to stop monitoring: Streams automatically clean up when tasks are cancelled
let task = Task { for await event in await manager.startUpdatingLocation() { ... } } // Later: task.cancel() // Stops location updates
-
Choose appropriate accuracy: Use lower accuracy when possible to save battery
let manager = AsyncLocationManager(desiredAccuracy: .hundredMetersAccuracy)
-
Add required Info.plist keys: Don't forget to add location usage descriptions
<key>NSLocationWhenInUseUsageDescription</key> <string>We need your location to show nearby places</string> <key>NSLocationAlwaysAndWhenInUseUsageDescription</key> <string>We need your location to provide location-based features</string>
Location updates not working
- Ensure you've added the required Info.plist keys
- Check that authorization has been granted
- Verify location services are enabled on the device
- Make sure you initialized on the main thread
Task cancelled warning
This is expected behavior when you cancel a Task that's monitoring location updates. The library properly cleans up resources.
Background location not working
- Add "Location updates" to Background Modes in Xcode capabilities
- Set
allowsBackgroundLocationUpdatestotrue - Request "Always" authorization, not just "When In Use"
Contributions are welcome! Please feel free to submit a Pull Request. For major changes:
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
- Follow Swift API design guidelines
- Add tests for new features
- Update documentation for public API changes
- Ensure code compiles on all supported platforms
AsyncLocationKit is released under the MIT License. See LICENSE for details.
MIT License
Copyright (c) 2022 AsyncSwift
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
- Built by the AsyncSwift team
- Inspired by the Swift concurrency revolution
- Thanks to all contributors and users
Made with β€οΈ by the AsyncSwift team