])
What is Hanson?
Hanson is a simple, lightweight library to observe and bind values in Swift. It's been developed to support the MVVM architecture in our Blendle iOS app. Hanson provides several advantages to using KVO in Swift, such as a Swiftier syntax, no boilerplate code, and the ability to use it in pure Swift types.
Example Usage
The most basic use case is to simply observe an Observable for changes:
let observable = Observable("Hello World")
observe(observable) { event in
// Invoked whenever observable.value is set.
print("Value changed from \(event.oldValue) to \(event.newValue)")
}
Hanson also provides a wrapper around KVO, so you can do the following to observe a UITextField's text property for changes:
let textField = UITextField()
let textFieldObservable = textField.dynamicObservable(keyPath: #keyPath(UITextField.text), type: String.self)
observe(textFieldObservable) { event in
print("Text field value changed from \(event.oldValue) to \(event.newValue)")
}
Furthermore, you can also use Hanson to bind an observable to another observable. Let's say we have a view model that's responsible for loading data, and we want the view to show an activity indicator while the view model is loading data:
class ViewModel {
let isLoadingData = Observable(false)
}
class View {
let showsActivityIndicator = Observable(false)
}
let viewModel = ViewModel()
let view = View()
bind(viewModel.isLoadingData, to: view.showsActivityIndicator)
Now, whenever the view model's isLoadingData property is set to a different value, it will automatically be set to the view's showsActivityIndicator property.
Binding is also supported from and to KVO-backed observables. To bind a text field's content to a label:
let textField = UITextField()
let textFieldObservable = textField.dynamicObservable(keyPath: #keyPath(UITextField.text), type: String.self)
let label = UILabel()
let labelObservable = label.dynamicObservable(keyPath: #keyPath(UILabel.text), type: String.self)
bind(textFieldObservable, to: labelObservable)
If you want to handle the binding yourself, you can also provide a closure that will be invoked when a new value should be set. In the following example, we'll bind an isLoadingData observable to a UIActivityIndicatorView:
let isLoadingData = Observable(false)
let activityIndicatorView = UIActivityIndicatorView()
bind(isLoadingData, to: activityIndicatorView) { activityIndicatorView, isLoadingData in
if isLoadingData {
activityIndicatorView.startAnimating()
} else {
activityIndicatorView.stopAnimating()
}
}
Hanson also supports observering notifications sent through a NotificationCenter. For example, to observe when an application is entering the background:
let observable = NotificationCenter.default.observable(for: Notification.Name.UIApplicationDidEnterBackground)
observe(observable) { notification in
print("Application did enter background")
}
Schedulers
Schedulers can be used to schedule the events of your observation. By default, Hanson uses the CurrentThreadScheduler, which immediatly sends events on whatever thread it currently is. Hanson also offers the MainThreadScheduler, which ensures events are sent on the main thread. This is useful when observing a value that can change from a background thread and you want to do UI changes based on that value. For example:
let observable = Observable("Hello World")
observe(observable, with: MainThreadScheduler()) { event in
// It's safe to do UI work here without calling DispatchQueue.main.async here
}
performOnBackground {
observable.value = "Hello from a background"
}
Schedulers are also supported when binding observables:
let isLoadingData = Observable(true)
let activityIndicatorView = UIActivityIndicatorView()
bind(isLoadingData, with: MainThreadScheduler(), to: activityIndicatorView) { activityIndicatorView, isLoadingData in
// It's safe to do UI work here without calling DispatchQueue.main.async here
}
performOnBackground {
isLoadingData.value = false
}
You can create your own scheduler by conforming to the EventScheduler protocol.
Requirements
- iOS 8.0+ / macOS 10.9+ / tvOS 9.0+
- Xcode 8
Installation
Hanson is available through either CocoaPods or Carthage.
Cocoapods
- Add
pod 'Hanson'to yourPodfile. - Run
pod install.
Carthage
- Add
github 'blendle/Hanson'to yourCartfile. - Run
carthage update. - Link the framework with your target as described in Carthage Readme.
Swift Package Manager
- In Xcode, select your project and scroll to
Frameworks, Libraries, and Embedded Content. - Click the
+. - At the bottom of the frameworks and libraries window that opens, select
Add other...and thenAdd package dependency.... - Paste
https://github.com/blendle/Hanson.gitin the search textfield and follow through with the assistant.
Building
The project obviously builds fine through Xcode, just load up Hanson.xcodeproj and run it.
For convenience, we've included a few scripts and a Makefile that allow you to build Hanson from the command line and through continuous integration. They are inspired by GitHub's Scripts to Rule Them All boilerplate:
|-- script/
|-- etc/
|-- config.sh # Contains basic configuration parameters
|-- bootstrap # Prepares the project
|-- setup # Sets up the local building process
|-- test # Runs tests locally
|-- cisetup # Sets up the CI building process
|-- citest # Runs tests in a CI environment
To get started:
$ make
To skip setup and immediately start testing:
$ make test
Make sure all tests pass before opening a Pull Request.
Release Notes
See CHANGELOG.md for a list of changes.
License
Hanson is released under the ISC license. See LICENSE for details.
20k Jan 8, 2023
230 Dec 27, 2022
687 Oct 26, 2022
1.1k Jan 3, 2023
133 Aug 17, 2022
25 Aug 16, 2022
28 Nov 8, 2022
104 Dec 26, 2022
55 Dec 20, 2022
8 Jun 28, 2020
324 Dec 17, 2022
1.2k Dec 9, 2022
4 Apr 8, 2022
149 Oct 9, 2022
613 Jan 3, 2023
719 Nov 19, 2022
67 Dec 7, 2020
6 Mar 26, 2021