Defaults

Defaults is a type-safe, modern wrapper around Apple's UserDefaults. It provides a facade that allows you to store key-value pairs persistently across app launches with several advanced features:

• Strongly typed: Declare types and default values upfront.
• Codable & NSSecureCoding support: Store complex types like enums or custom structs.
• SwiftUI Integration: Use property wrappers for reactive UI updates.
• Observation: Monitor changes to specific keys.
• iCloud Support: Automatically synchronize data across devices.
• Debuggable: Data is stored as JSON-serialized values.

Any type conforming to Codable or NSSecureCoding can be used.

Note on precedence: If a type conforms to both NSSecureCoding and Codable, Codable is used for serialization by default. You can override this behavior using the advanced bridging configuration.

If you want to use Defaults and @Default throughout your app without adding import Defaults to every file, you can create typealiases in a central file within your app.

import Defaults

typealias Defaults = _Defaults
typealias Default = _Default

You can make custom containers (like bespoke Bags or Sets) persistable by conforming to specific protocols:

• For Collection types: Conform to Defaults.CollectionSerializable. Defaults needs a way to turn the collection into an array and back again.
• For Set algebra types: Conform to Defaults.SetAlgebraSerializable. You must implement toArray() -> [Element] to facilitate serialization.

struct Bag<Element: Defaults.Serializable>: Collection {
	var items: [Element]
	// ... implement Collection requirements ...
}

extension Bag: Defaults.CollectionSerializable {
	init(_ elements: [Element]) {
		self.items = elements
	}
}

// Usage
extension Defaults.Keys {
	static let stringBag = Key<Bag<String>>("stringBag", default: Bag(["Hello", "World!"]))
}

To use Defaults, extend Defaults.Keys to define your keys. Each key is a Key<T> where T is the type of the value and the second parameter is the default value. You can then access and modify these values using the Defaults subscript.

import Defaults

extension Defaults.Keys {
	static let quality = Key<Double>("quality", default: 0.8)
}

// Accessing values
Defaults[.quality]
//=> 0.8

// Setting values
Defaults[.quality] = 0.5
//=> 0.5

To ensure type safety and centralize your configuration, extend Defaults.Keys with static properties using the Key<T> type. This allows you to define the key name and its default value in one place. You can then access or modify these values using the Defaults subscript with the key you defined.

import Defaults

extension Defaults.Keys {
	static let quality = Key<Double>("quality", default: 0.8)
}

// Reading a value
Defaults[.quality]
//=> 0.8

// Writing a value
Defaults[.quality] = 0.5
//=> 0.5

To migrate from SwiftUI's @AppStorage to Defaults, centralize your keys in an extension of Defaults.Keys and replace the @AppStorage property wrapper with @Default. This provides better type safety and centralized management.

// Before (with @AppStorage):
struct SettingsView: View {
	@AppStorage("showPreview") var showPreview = true

	var body: some View {
		Toggle("Show Preview", isOn: $showPreview)
	}
}

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

struct SettingsView: View {
	@Default(.showPreview) var showPreview

	var body: some View {
		Toggle("Show Preview", isOn: $showPreview)
	}
}

To use Defaults, you must first declare keys. The recommended pattern is to extend Defaults.Keys with static properties of type Key<T>.

Key Naming Rules:

• Must be ASCII.
• Cannot start with @.
• Cannot contain a dot (.).

You can declare keys with a fixed default value, an optional type (which defaults to nil), or a dynamic default value using a closure.

import Defaults

// Fixed default value
extension Defaults.Keys {
	static let quality = Key<Double>("quality", default: 0.8)
}

// Optional key (defaults to nil)
extension Defaults.Keys {
	static let name = Key<String?>("name")
}

// Dynamic default value
extension Defaults.Keys {
	static let camera = Key<AVCaptureDevice?>("camera") { .default(for: .video) }
}

// Using keys directly without extension
let isUnicorn = Defaults.Key<Bool>("isUnicorn", default: true)

To add Defaults to your Xcode project, use the Swift Package Manager by adding the following URL in the "Swift Package Manager" tab in Xcode:

https://github.com/sindresorhus/Defaults