ForgeLocation

Location triggers for iOS — geofencing, significant changes, and visits.

---

ForgeLocation wraps CLLocationManager in a handler-based registry. Register your handlers, declare which events they care about, and ForgeLocation dispatches matching events to them — including from the background.

Monitoring types

Type	Triggers on	Battery	Survives termination
Region monitoring	Enter/exit circular region	Low	✅
Significant changes	~500m movement	Very low	✅ relaunches app
Visit monitoring	Arrival / departure at a place	Minimal	✅

All three deliver events in the background via the same handler pattern.

Features

• Handler-based dispatch — define small handlers, declare interests, let the registry route events
• Unified event model — LocationTriggerEvent wraps region, significant-change, visit, and error events in one enum
• Concurrent dispatch — matching handlers run concurrently within the background time budget
• Dependency-injected observers — registry takes ConnectivityObserving and ProtectedDataObserving from ForgeObservers or your own implementations
• Sendable value types — Coordinate, LocationSnapshot, RegionEvent, and VisitEvent all conform to Sendable with public initializers for tests and analytics replay

Requirements

• iOS 18+
• Swift 6.3+ (Xcode 26 or later)
• Always location authorization for background delivery
• NSLocationAlwaysAndWhenInUseUsageDescription and location background mode in Info.plist

Installation

Xcode

1. File → Add Package Dependencies…
2. Paste https://github.com/stefanprojchev/ForgeLocation.git
3. Set rule to Up to Next Major from 1.0.0

Package.swift

dependencies:[.package(url:"https://github.com/stefanprojchev/ForgeLocation.git", from:"1.0.0")],targets:[.target(
name:"YourApp",
dependencies:["ForgeLocation"])]

Quick Start

1. Define a handler

import ForgeLocation
finalclassGeofenceNotificationHandler:LocationTriggerHandler{letid="geofence.notification"letinterests:Set<LocationTriggerInterest>=[.regionEnter,.regionExit]func handle(_ event:LocationTriggerEvent, context:LocationTriggerContext)async{switch event {case.regionEntered(let region):awaitNotificationService.send(
title:"Welcome!",
body:"You arrived at \(region.regionIdentifier)")case.regionExited(let region):awaitNotificationService.send(
title:"Goodbye!",
body:"You left \(region.regionIdentifier)")default:break}}}

2. Register and start monitoring

import ForgeLocation
import ForgeObservers
@MainActorfunc setupLocation(){letregistry=LocationTriggerRegistry(
connectivity:ConnectivityObserver(),
protectedData:ProtectedDataObserver())
registry.addHandler(GeofenceNotificationHandler())
registry.addHandler(LocationAnalyticsHandler())
registry.requestAlwaysAuthorization()
// Monitor a circular region around the office
registry.addRegion(
identifier:"office",
center:Coordinate(latitude:41.9981, longitude:21.4254),
radius:200)
registry.startSignificantLocationChanges()
registry.startVisitMonitoring()}

Info.plist

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Used to trigger notifications when you arrive at or leave key locations.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to show content relevant to your location.</string>
<key>UIBackgroundModes</key>
<array>
<string>location</string>
</array>

The Forge Family

ForgeLocation is part of the Forge family of Swift packages for iOS.

Package	Description
ForgeCore	Thread-safe primitives for iOS Swift packages.
ForgeInject	Dependency injection with constructor and property wrapper support.
ForgeObservers	Reactive system observers — connectivity, lifecycle, keyboard, and more.
ForgeStorage	Type-safe key-value, file, and Keychain storage.
ForgeDB	Type-safe repository pattern and GRDB-backed SQLite persistence.
ForgeOrchestrator	Orchestrate app flows — startup gates, data pipelines, and continuous monitors.
ForgePush	Push notification management — permissions, tokens, and routing.
ForgeLocation	Location triggers — geofencing, significant changes, and visits.
ForgeBackgroundTasks	Background task scheduling and dispatch.
ForgeNetworking	Typed, async/await-first HTTP networking with auth, retry, and background transfers.
ForgeLog	Structured logging with pluggable providers and a built-in inspector UI.
ForgeAccess	Subscription-aware feature gating with override channels and debug UI.

License

ForgeLocation is released under the MIT License. See LICENSE.