Defaults
Swifty and modern UserDefaults
Store key-value pairs persistently across launches of your app.
It uses NSUserDefaults
underneath but exposes a type-safe facade with lots of nice conveniences.
It's used in production by apps like Gifski, Dato, Lungo, Battery Indicator, and HEIC Converter.
For a real-world example, see my Plash app.
Highlights
- Strongly typed: You declare the type and default value upfront.
- Codable support: You can store any Codable value, like an enum.
- NSSecureCoding support: You can store any NSSecureCoding value.
- SwiftUI: Property wrapper that updates the view when the
UserDefaults
value changes. - Publishers: Combine publishers built-in.
- Observation: Observe changes to keys.
- Debuggable: The data is stored as JSON-serialized values.
Compatibility
- macOS 10.12+
- iOS 10+
- tvOS 10+
- watchOS 3+
Install
Swift Package Manager
Add https://github.com/sindresorhus/Defaults
in the “Swift Package Manager” tab in Xcode.
Carthage
github "sindresorhus/Defaults"
CocoaPods
pod 'Defaults'
Usage
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 = Key<Double?>("name")
}
if let name = Defaults[.name] {
print(name)
}
The default value is then nil
.
If you have NSSecureCoding
classes which you want to save, you can use them as follows:
extension Defaults.Keys {
static let someSecureCoding = NSSecureCodingKey<SomeNSSecureCodingClass>("someSecureCoding", default: SomeNSSecureCodingClass(string: "Default", int: 5, bool: true))
static let someOptionalSecureCoding = NSSecureCodingOptionalKey<Double>("someOptionalSecureCoding")
}
Defaults[.someSecureCoding].string
//=> "Default"
Defaults[.someSecureCoding].int
//=> 5
Defaults[.someSecureCoding].bool
//=> true
You can use those keys just like in all the other examples. The return value will be your NSSecureCoding
class.
Enum example
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"
Use keys directly
You are not required to attach keys to Defaults.Keys
.
let isUnicorn = Defaults.Key<Bool>("isUnicorn", default: true)
Defaults[isUnicorn]
//=> true
SwiftUI support
You can use the @Default
property wrapper to get/set a Defaults
item and also have the view be updated when the value changes. This is similar to @State
.
extension Defaults.Keys {
static let hasUnicorn = Key<Bool>("hasUnicorn", default: false)
}
struct ContentView: View {
@Default(.hasUnicorn) var hasUnicorn
var body: some View {
Text("Has Unicorn: \(hasUnicorn)")
Toggle("Toggle Unicorn", isOn: $hasUnicorn)
}
}
Note that it's @Default
, not @Defaults
.
You cannot use @Default
in an ObservableObject
. It's meant to be used in a View
.
This is only implemented for Defaults.Key
. PR welcome for Defaults.NSSecureCoding
if you need it.
Observe changes to a key
extension 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] = true
In contrast to the native UserDefaults
key observation, here you receive a strongly-typed change object.
There is also an observation API using the Combine framework, exposing a Publisher for key changes:
let publisher = Defaults.publisher(.isUnicornMode)
let cancellable = publisher.sink { 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] = true
// To invalidate the observation.
cancellable.cancel()
Invalidate observations automatically
extension Defaults.Keys {
static let isUnicornMode = Key<Bool>("isUnicornMode", default: false)
}
final class Foo {
init() {
Defaults.observe(.isUnicornMode) { change in
print(change.oldValue)
print(change.newValue)
}.tieToLifetime(of: self)
}
}
Defaults[.isUnicornMode] = true
The observation will be valid until self
is deinitialized.
Reset keys to their default values
extension Defaults.Keys {
static let isUnicornMode = Key<Bool>("isUnicornMode", default: false)
}
Defaults[.isUnicornMode] = true
//=> true
Defaults.reset(.isUnicornMode)
Defaults[.isUnicornMode]
//=> false
This works for a Key
with an optional too, which will be reset back to nil
.
Control propagation of change events
Changes made within the Defaults.withoutPropagation
closure will not be propagated to observation callbacks (Defaults.observe()
or Defaults.publisher()
), and therefore could prevent infinite recursion.
let observer = Defaults.observe(keys: .key1, .key2) {
// …
Defaults.withoutPropagation {
// Update `.key1` without propagating the change to listeners.
Defaults[.key1] = 11
}
// This will be propagated.
Defaults[.someKey] = true
}
UserDefaults
with sugar
It's just This works too:
extension Defaults.Keys {
static let isUnicorn = Key<Bool>("isUnicorn", default: true)
}
UserDefaults.standard[.isUnicorn]
//=> true
UserDefaults
Shared let 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]
//=> true
UserDefaults
Default values are registered with When 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: Defaults.Keys.isUnicornMode.name))
//=> true
API
Defaults
Defaults.Keys
Type: class
Stores the keys.
Defaults.Key
(alias Defaults.Keys.Key
)
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.NSSecureCodingKey
(alias Defaults.Keys.NSSecureCodingKey
)
Defaults.NSSecureCodingKey<T>(_ key: String, default: T, suite: UserDefaults = .standard)
Type: class
Create a NSSecureCoding 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.NSSecureCodingOptionalKey
(alias Defaults.Keys.NSSecureCodingOptionalKey
)
Defaults.NSSecureCodingOptionalKey<T>(_ key: String, suite: UserDefaults = .standard)
Type: class
Create a NSSecureCoding key with an optional value.
Defaults.reset(keys…)
Type: func
Reset the given keys back to their default values.
You can specify up to 10 keys. If you need to specify more, call this method multiple times.
You can also specify string keys, which can be useful if you need to store some keys in a collection, as it's not possible to store Defaults.Key
in a collection because it's generic.
Defaults.observe
Defaults.observe<T: Codable>(
_ key: Defaults.Key<T>,
options: ObservationOptions = [.initial],
handler: @escaping (KeyChange<T>) -> Void
) -> Defaults.Observation
Defaults.observe<T: NSSecureCoding>(
_ key: Defaults.NSSecureCodingKey<T>,
options: ObservationOptions = [.initial],
handler: @escaping (NSSecureCodingKeyChange<T>) -> Void
) -> Defaults.Observation
Defaults.observe<T: NSSecureCoding>(
_ key: Defaults.NSSecureCodingOptionalKey<T>,
options: ObservationOptions = [.initial],
handler: @escaping (NSSecureCodingOptionalKeyChange<T>) -> Void
) -> Defaults.Observation
Type: 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.observe(keys: keys..., options:)
Type: func
Observe multiple keys of any type, but without any information about the changes.
Options are the same as in .observe(…)
for a single key.
Defaults.publisher(_ key:, options:)
Defaults.publisher<T: Codable>(
_ key: Defaults.Key<T>,
options: ObservationOptions = [.initial]
) -> AnyPublisher<KeyChange<T>, Never>
Defaults.publisher<T: NSSecureCoding>(
_ key: Defaults.NSSecureCodingKey<T>,
options: ObservationOptions = [.initial]
) -> AnyPublisher<NSSecureCodingKeyChange<T>, Never>
Defaults.publisher<T: NSSecureCoding>(
_ key: Defaults.NSSecureCodingOptionalKey<T>,
options: ObservationOptions = [.initial]
) -> AnyPublisher<NSSecureCodingOptionalKeyChange<T>, Never>
Type: func
Observation API using Publisher from the Combine framework.
Available on macOS 10.15+, iOS 13.0+, tvOS 13.0+, and watchOS 6.0+.
Defaults.publisher(keys: keys…, options:)
Type: func
Combine observation API for multiple key observation, but without specific information about changes.
Available on macOS 10.15+, iOS 13.0+, tvOS 13.0+, and watchOS 6.0+.
Defaults.removeAll
Defaults.removeAll(suite: UserDefaults = .standard)
Type: func
Remove all entries from the given UserDefaults
suite.
Defaults.Observation
Type: protocol
Represents an observation of a defaults key.
Defaults.Observation#invalidate
Defaults.Observation#invalidate()
Type: func
Invalidate the observation.
Defaults.Observation#tieToLifetime
@discardableResult
Defaults.Observation#tieToLifetime(of weaklyHeldObject: AnyObject) -> Self
Type: func
Keep the observation alive for as long as, and no longer than, another object exists.
When weaklyHeldObject
is deinitialized, the observation is invalidated automatically.
Defaults.Observation.removeLifetimeTie
Defaults.Observation#removeLifetimeTie()
Type: func
Break the lifetime tie created by tieToLifetime(of:)
, if one exists.
The effects of any call to tieToLifetime(of:)
are reversed. Note however that if the tied-to object has already died, then the observation is already invalid and this method has no logical effect.
Defaults.withoutPropagation(_ closure:)
Execute the closure without triggering change events.
Any Defaults
key changes made within the closure will not propagate to Defaults
event listeners (Defaults.observe()
and Defaults.publisher()
). This can be useful to prevent infinite recursion when you want to change a key in the callback listening to changes for the same key.
@Default(_ key:)
Get/set a Defaults
item and also have the view be updated when the value changes.
This is only implemented for Defaults.Key
. PR welcome for Defaults.NSSecureCoding
if you need it.
FAQ
How can I store a dictionary of arbitrary values?
You cannot store [String: Any]
directly as it cannot conform to Codable
. However, you can use the AnyCodable
package to work around this Codable
limitation:
import AnyCodable
extension Defaults.Keys {
static let magic = Key<[String: AnyCodable]>("magic", default: [:])
}
// …
Defaults[.magic]["unicorn"] = "🦄"
if let value = Defaults[.magic]["unicorn"]?.value {
print(value)
//=> "🦄"
}
Defaults[.magic]["number"] = 3
Defaults[.magic]["boolean"] = true
SwiftyUserDefaults
?
How is this different from 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.
Maintainers
Related
- Preferences - Add a preferences window to your macOS app
- KeyboardShortcuts - Add user-customizable global keyboard shortcuts to your macOS app
- 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…