XUtils

Defaults

Strongly-typed UserDefaults with support for Codable and key observation.

Swift
https://github.com/sindresorhus/Defaults

Defaults

Swifty and modern UserDefaults

Store key-value pairs persistently across launches of your app.

It uses UserDefaults underneath but exposes a type-safe facade with lots of nice conveniences.

It’s used in production by all my apps (1 million+ users).

Compatibility

  • macOS 11+
  • iOS 14+
  • tvOS 14+
  • watchOS 9+
  • visionOS 1+

Install

Add https://github.com/sindresorhus/Defaults in the “Swift Package Manager” tab in Xcode.

Codable example

struct User: Codable, Defaults.Serializable {
	let name: String
	let age: String
}

extension Defaults.Keys {
	static let user = Key<User>("user", default: .init(name: "Hello", age: "24"))
}

Defaults[.user].name
//=> "Hello"

Use keys directly

You are not required to attach keys to Defaults.Keys.

let isUnicorn = Defaults.Key<Bool>("isUnicorn", default: true)

Defaults[isUnicorn]
//=> true

@Default

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", isOn: $hasUnicorn)
		Button("Reset") {
			_hasUnicorn.reset()
		}
	}
}

Note that it’s @Default, not @Defaults.

You cannot use @Default in an ObservableObject. It’s meant to be used in a View.

Toggle

There’s also a SwiftUI.Toggle wrapper that makes it easier to create a toggle based on a Defaults key with a Bool value.

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

struct ShowAllDayEventsSetting: View {
	var body: some View {
		Defaults.Toggle("Show All-Day Events", key: .showAllDayEvents)
	}
}

You can also listen to changes:

struct ShowAllDayEventsSetting: View {
	var body: some View {
		Defaults.Toggle("Show All-Day Events", key: .showAllDayEvents)
			// Note that this has to be directly attached to `Defaults.Toggle`. It's not `View#onChange()`.
			.onChange {
				print("Value", $0)
			}
	}
}

Observe changes to a key

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

// …

Task {
	for await value in Defaults.updates(.isUnicornMode) {
		print("Value:", value)
	}
}

In contrast to the native UserDefaults key observation, here you receive a strongly-typed change object.

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
	}

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: Defaults.Keys.isUnicornMode.name))
//=> true

Note A Defaults.Key with a dynamic default value will not register the default value in UserDefaults.

API

Defaults

Defaults.Keys

Type: class

Stores the keys.

Defaults.Key (alias Defaults.Keys.Key)

Defaults.Key<T>(_ name: 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.Serializable

public protocol DefaultsSerializable {
	typealias Value = Bridge.Value
	typealias Serializable = Bridge.Serializable
	associatedtype Bridge: Defaults.Bridge

	static var bridge: Bridge { get }
}

Type: protocol

Types that conform to this protocol can be used with Defaults.

The type should have a static variable bridge which should reference an instance of a type that conforms to Defaults.Bridge.

Defaults.Bridge

public protocol DefaultsBridge {
	associatedtype Value
	associatedtype Serializable

	func serialize(_ value: Value?) -> Serializable?
	func deserialize(_ object: Serializable?) -> Value?
}

Type: protocol

A Bridge is responsible for serialization and deserialization.

It has two associated types Value and Serializable.

  • Value: The type you want to use.
  • Serializable: The type stored in UserDefaults.
  • serialize: Executed before storing to the UserDefaults .
  • deserialize: Executed after retrieving its value from the UserDefaults.

Defaults.AnySerializable

Defaults.AnySerializable<Value: Defaults.Serializable>(_ value: Value)

Type: class

Type-erased wrapper for Defaults.Serializable values.

  • get<Value: Defaults.Serializable>() -> Value?: Retrieve the value which type is Value from UserDefaults.
  • get<Value: Defaults.Serializable>(_: Value.Type) -> Value?: Specify the Value you want to retrieve. This can be useful in some ambiguous cases.
  • set<Value: Defaults.Serializable>(_ newValue: Value): Set a new value for Defaults.AnySerializable.

Defaults.reset(keys…)

Type: func

Reset the given keys back to their default values.

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

Defaults.removeAll(suite: UserDefaults = .standard)

Type: func

Remove all entries from the given UserDefaults suite.

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 SwiftUI view be updated when the value changes.

Advanced

Defaults.CollectionSerializable

public protocol DefaultsCollectionSerializable: Collection, Defaults.Serializable {
	init(_ elements: [Element])
}

Type: protocol

A Collection which can store into the native UserDefaults.

It should have an initializer init(_ elements: [Element]) to let Defaults do the de-serialization.

Defaults.SetAlgebraSerializable

public protocol DefaultsSetAlgebraSerializable: SetAlgebra, Defaults.Serializable {
	func toArray() -> [Element]
}

Type: protocol

A SetAlgebra which can store into the native UserDefaults.

It should have a function func toArray() -> [Element] to let Defaults do the serialization.

Dynamic value

There might be situations where you want to use [String: Any] directly, but Defaults need its values to conform to Defaults.Serializable. The type-eraser Defaults.AnySerializable helps overcome this limitation.

Defaults.AnySerializable is only available for values that conform to Defaults.Serializable.

Warning: The type-eraser should only be used when there’s no other way to handle it because it has much worse performance. It should only be used in wrapped types. For example, wrapped in Array, Set or Dictionary.

Primitive type

Defaults.AnySerializable conforms to ExpressibleByStringLiteral, ExpressibleByIntegerLiteral, ExpressibleByFloatLiteral, ExpressibleByBooleanLiteral, ExpressibleByNilLiteral, ExpressibleByArrayLiteral, and ExpressibleByDictionaryLiteral.

Which means you can assign these primitive types directly:

let any = Defaults.Key<Defaults.AnySerializable>("anyKey", default: 1)
Defaults[any] = "🦄"

Other types

Using get and set

For other types, you will have to assign it like this:

enum mime: String, Defaults.Serializable {
	case JSON = "application/json"
	case STREAM = "application/octet-stream"
}

let any = Defaults.Key<Defaults.AnySerializable>("anyKey", default: [Defaults.AnySerializable(mime.JSON)])

if let mimeType: mime = Defaults[any].get() {
	print(mimeType.rawValue)
	//=> "application/json"
}

Defaults[any].set(mime.STREAM)

if let mimeType: mime = Defaults[any].get() {
	print(mimeType.rawValue)
	//=> "application/octet-stream"
}

Serialization for ambiguous Codable type

You may have a type that conforms to Codable & NSSecureCoding or a Codable & RawRepresentable enum. By default, Defaults will prefer the Codable conformance and use the CodableBridge to serialize it into a JSON string. If you want to serialize it as a NSSecureCoding data or use the raw value of the RawRepresentable enum, you can conform to Defaults.PreferNSSecureCoding or Defaults.PreferRawRepresentable to override the default bridge:

enum mime: String, Codable, Defaults.Serializable, Defaults.PreferRawRepresentable {
	case JSON = "application/json"
}

extension Defaults.Keys {
	static let magic = Key<[String: Defaults.AnySerializable]>("magic", default: [:])
}

print(UserDefaults.standard.string(forKey: "magic"))
//=> application/json

Had we not added Defaults.PreferRawRepresentable, the stored representation would have been "application/json" instead of application/json.

This can also be useful if you conform a type you don’t control to Defaults.Serializable as the type could receive Codable conformance at any time and then the stored representation would change, which could make the value unreadable. By explicitly defining which bridge to use, you ensure the stored representation will always stay the same.

Custom Collection type

  1. Create your Collection and make its elements conform to Defaults.Serializable.
struct Bag<Element: Defaults.Serializable>: Collection {
	var items: [Element]

	var startIndex: Int { items.startIndex }
	var endIndex: Int { items.endIndex }

	mutating func insert(element: Element, at: Int) {
		items.insert(element, at: at)
	}

	func index(after index: Int) -> Int {
		items.index(after: index)
	}

	subscript(position: Int) -> Element {
		items[position]
	}
}
  1. Create an extension of Bag that conforms to Defaults.CollectionSerializable.
extension Bag: Defaults.CollectionSerializable {
	init(_ elements: [Element]) {
		self.items = elements
	}
}
  1. Create some keys and enjoy it.
extension Defaults.Keys {
	static let stringBag = Key<Bag<String>>("stringBag", default: Bag(["Hello", "World!"]))
}

Defaults[.stringBag][0] //=> "Hello"
Defaults[.stringBag][1] //=> "World!"

Custom SetAlgebra type

  1. Create your SetAlgebra and make its elements conform to Defaults.Serializable & Hashable
struct SetBag<Element: Defaults.Serializable & Hashable>: SetAlgebra {
	var store = Set<Element>()

	init() {}

	init(_ store: Set<Element>) {
		self.store = store
	}

	func contains(_ member: Element) -> Bool {
		store.contains(member)
	}

	func union(_ other: SetBag) -> SetBag {
		SetBag(store.union(other.store))
	}

	func intersection(_ other: SetBag) -> SetBag {
		var setBag = SetBag()
		setBag.store = store.intersection(other.store)
		return setBag
	}

	func symmetricDifference(_ other: SetBag) -> SetBag {
		var setBag = SetBag()
		setBag.store = store.symmetricDifference(other.store)
		return setBag
	}

	@discardableResult
	mutating func insert(_ newMember: Element) -> (inserted: Bool, memberAfterInsert: Element) {
		store.insert(newMember)
	}

	mutating func remove(_ member: Element) -> Element? {
		store.remove(member)
	}

	mutating func update(with newMember: Element) -> Element? {
		store.update(with: newMember)
	}

	mutating func formUnion(_ other: SetBag) {
		store.formUnion(other.store)
	}

	mutating func formSymmetricDifference(_ other: SetBag) {
		store.formSymmetricDifference(other.store)
	}

	mutating func formIntersection(_ other: SetBag) {
		store.formIntersection(other.store)
	}
}
  1. Create an extension of SetBag that conforms to Defaults.SetAlgebraSerializable
extension SetBag: Defaults.SetAlgebraSerializable {
	func toArray() -> [Element] {
		Array(store)
	}
}
  1. Create some keys and enjoy it.
extension Defaults.Keys {
	static let stringSet = Key<SetBag<String>>("stringSet", default: SetBag(["Hello", "World!"]))
}

Defaults[.stringSet].contains("Hello") //=> true
Defaults[.stringSet].contains("World!") //=> true

FAQ

Maintainers

Former

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

Articles

  • coming soon...