mirrors
/
Defaults
mirror of https://github.com/sindresorhus/Defaults.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Defaults/readme.md

13 KiB
Raw Blame History

Defaults Build Status

Swifty and modern UserDefaults

Note: The readme reflects the master branch. Click here for docs for the latest version. The code in the master branch cannot be released until Apple fixes this bug.

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.

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.
  • Debuggable: The data is stored as JSON-serialized values.
  • Observation: Observe changes to keys.
  • Publishers: Combine publishers built-in.
  • Lightweight: It's only some hundred lines of code.

Compatibility

  • macOS 10.12+
  • iOS 10+
  • tvOS 10+
  • watchOS 3+

Install

SwiftPM

.package(url: "https://github.com/sindresorhus/Defaults", from: "3.1.1")

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

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.

It's just UserDefaults with sugar

This works too:

extension Defaults.Keys {
	static let isUnicorn = Key<Bool>("isUnicorn", default: true)
}

UserDefaults.standard[.isUnicorn]
//=> true

Shared UserDefaults

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

Default values are registered with UserDefaults

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: 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

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.NSSecureCodingKey<T>..., suite: UserDefaults = .standard)
Defaults.reset<T: Codable>(_ keys: [Defaults.NSSecureCodingKey<T>], suite: UserDefaults = .standard)
Defaults.reset<T: Codable>(_ keys: Defaults.NSSecureCodingOptionalKey<T>..., suite: UserDefaults = .standard)
Defaults.reset<T: Codable>(_ keys: [Defaults.NSSecureCodingOptionalKey<T>], suite: UserDefaults = .standard)

Type: func

Reset the given keys back to their default values.

Defaults.observe

Defaults.observe<T: Codable>(
	_ key: Defaults.Key<T>,
	options: NSKeyValueObservingOptions = [.initial, .old, .new],
	handler: @escaping (KeyChange<T>) -> Void
) -> Defaults.Observation

Defaults.observe<T: NSSecureCoding>(
	_ key: Defaults.NSSecureCodingKey<T>,
	options: NSKeyValueObservingOptions = [.initial, .old, .new],
	handler: @escaping (NSSecureCodingKeyChange<T>) -> Void
) -> Defaults.Observation

Defaults.observe<T: NSSecureCoding>(
	_ key: Defaults.NSSecureCodingOptionalKey<T>,
	options: NSKeyValueObservingOptions = [.initial, .old, .new],
	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.publisher

Defaults.publisher<T: Codable>(
	_ key: Defaults.Key<T>,
	options: NSKeyValueObservingOptions = [.initial, .old, .new]
) -> AnyPublisher<KeyChange<T>, Never>

Defaults.publisher<T: NSSecureCoding>(
	_ key: Defaults.NSSecureCodingKey<T>,
	options: NSKeyValueObservingOptions = [.initial, .old, .new]
) -> AnyPublisher<NSSecureCodingKeyChange<T>, Never>

Defaults.publisher<T: NSSecureCoding>(
	_ key: Defaults.NSSecureCodingOptionalKey<T>,
	options: NSKeyValueObservingOptions = [.initial, .old, .new]
) -> 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:)

Defaults.publisher<T: Codable>(
	keys: Defaults.Key<T>...,
	options: NSKeyValueObservingOptions = [.initial, .old, .new]
) -> AnyPublisher<Void, Never> {

Defaults.publisher<T: NSSecureCoding>(
	keys: Defaults.NSSecureCodingKey<T>...,
	options: NSKeyValueObservingOptions = [.initial, .old, .new]
) -> AnyPublisher<Void, Never> {

Defaults.publisher<T: NSSecureCoding>(
	keys: Defaults.NSSecureCodingOptionalKey<T>...,
	options: NSKeyValueObservingOptions = [.initial, .old, .new]
) -> AnyPublisher<Void, Never> {

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.publisherAll

Defaults.publisherAll(initialEvent: Bool = true) -> AnyPublisher<UserDefaults, Never>

Convenience Publisher for all UserDefaults key change events. A wrapper around the UserDefaults.didChangeNotification notification.

  • Parameter initialEvent: Trigger an initial event immediately.

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 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.

FAQ

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.

Related

  • 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…