Swifty and modern UserDefaults
This package is used in production by apps like Gifski, Dato, Lungo, Battery Indicator, and HEIC Converter.
- Strongly typed: You declare the type and default value upfront.
- Codable support: You can store any Codable value, like an enum.
- Debuggable: The data is stored as JSON-serialized values.
- Observation: Observe changes to keys.
- Lightweight: It's only ~300 lines of code.
- macOS 10.12+
- iOS 10+
- tvOS 10+
- watchOS 3+
.package(url: "https://github.com/sindresorhus/Defaults", from: "3.0.0")github "sindresorhus/Defaults"
pod 'Defaults'You declare the defaults keys upfront with type and default value.
import Cocoa
import Defaults
extension Defaults.Keys {
static let quality = Key<Double>("quality", default: 0.8)
// ^ ^ ^ ^
// Key Type UserDefaults name Default value
}You can then access it as a subscript on the Defaults global:
Defaults[.quality]
//=> 0.8
Defaults[.quality] = 0.5
//=> 0.5
Defaults[.quality] += 0.1
//=> 0.6
Defaults[.quality] = "🦄"
//=> [Cannot assign value of type 'String' to type 'Double']You can also declare optional keys for when you don't want to declare a default value upfront:
extension Defaults.Keys {
static let name = OptionalKey<Double>("name")
}
if let name = Defaults[.name] {
print(name)
}The default value is then nil.
enum DurationKeys: String, Codable {
case tenMinutes = "10 Minutes"
case halfHour = "30 Minutes"
case oneHour = "1 Hour"
}
extension Defaults.Keys {
static let defaultDuration = Key<DurationKeys>("defaultDuration", default: .oneHour)
}
Defaults[.defaultDuration].rawValue
//=> "1 Hour"You are not required to attach keys to Defaults.Keys.
let isUnicorn = Defaults.Key<Bool>("isUnicorn", default: true)
Defaults[isUnicorn]
//=> trueextension Defaults.Keys {
static let isUnicornMode = Key<Bool>("isUnicornMode", default: false)
}
let observer = Defaults.observe(.isUnicornMode) { change in
// Initial event
print(change.oldValue)
//=> false
print(change.newValue)
//=> false
// First actual event
print(change.oldValue)
//=> false
print(change.newValue)
//=> true
}
Defaults[.isUnicornMode] = trueIn contrast to the native UserDefaults key observation, here you receive a strongly-typed change object.
extension Defaults.Keys {
static let isUnicornMode = Key<Bool>("isUnicornMode", default: false)
}
Defaults[.isUnicornMode] = true
//=> true
Defaults.reset(.isUnicornMode)
Defaults[.isUnicornMode]
//=> falseThis works for OptionalKey too, which will be reset back to nil.
This works too:
extension Defaults.Keys {
static let isUnicorn = Key<Bool>("isUnicorn", default: true)
}
UserDefaults.standard[.isUnicorn]
//=> truelet extensionDefaults = UserDefaults(suiteName: "com.unicorn.app")!
extension Defaults.Keys {
static let isUnicorn = Key<Bool>("isUnicorn", default: true, suite: extensionDefaults)
}
Defaults[.isUnicorn]
//=> true
// Or
extensionDefaults[.isUnicorn]
//=> trueWhen you create a Defaults.Key, it automatically registers the default value with normal UserDefaults. This means you can make use of the default value in, for example, bindings in Interface Builder.
extension Defaults.Keys {
static let isUnicornMode = Key<Bool>("isUnicornMode", default: true)
}
print(UserDefaults.standard.bool(forKey: isUnicornMode.name))
//=> trueType: class
Stores the keys.
Defaults.Key<T>(_ key: String, default: T, suite: UserDefaults = .standard)Type: class
Create a key with a default value.
The default value is written to the actual UserDefaults and can be used elsewhere. For example, with a Interface Builder binding.
Defaults.OptionalKey<T>(_ key: String, suite: UserDefaults = .standard)Type: class
Create a key with an optional value.
Defaults.reset<T: Codable>(_ keys: Defaults.Key<T>..., suite: UserDefaults = .standard)
Defaults.reset<T: Codable>(_ keys: [Defaults.Key<T>], suite: UserDefaults = .standard)
Defaults.reset<T: Codable>(_ keys: Defaults.OptionalKey<T>..., suite: UserDefaults = .standard)
Defaults.reset<T: Codable>(_ keys: [Defaults.OptionalKey<T>], suite: UserDefaults = .standard)Type: func
Reset the given keys back to their default values.
Defaults.observe<T: Codable>(
_ key: Defaults.Key<T>,
options: NSKeyValueObservingOptions = [.initial, .old, .new],
handler: @escaping (KeyChange<T>) -> Void
) -> DefaultsObservationDefaults.observe<T: Codable>(
_ key: Defaults.OptionalKey<T>,
options: NSKeyValueObservingOptions = [.initial, .old, .new],
handler: @escaping (OptionalKeyChange<T>) -> Void
) -> DefaultsObservationType: func
Observe changes to a key or an optional key.
By default, it will also trigger an initial event on creation. This can be useful for setting default values on controls. You can override this behavior with the options argument.
Defaults.removeAll(suite: UserDefaults = .standard)Type: func
Remove all entries from the UserDefaults suite.
How is this different from SwiftyUserDefaults?
It's inspired by that package and other solutions. The main difference is that this module doesn't hardcode the default values and comes with Codable support.
- Preferences - Add a preferences window to your macOS app in minutes
- LaunchAtLogin - Add "Launch at Login" functionality to your macOS app
- DockProgress - Show progress in your app's Dock icon
- Gifski - Convert videos to high-quality GIFs on your Mac
- More…
