Foil
A lightweight property wrapper for UserDefaults done right
About
Read the post: A better approach to writing a UserDefaults Property Wrapper
Why the name?
Foil, as in "let me quickly and easily wrap and store this leftover food in some foil so I can eat it later." 🌯 😉
Foil:
noun
North America
A very thin, pliable, easily torn sheet of aluminum used for cooking, packaging, cosmetics, and insulation.
Usage
You can use @FoilDefaultStorage
for non-optional values and @FoilDefaultStorageOptional
for optional ones.
You may wish to store all your user defaults in one place, however, that is not necessary. Any property on any type can use this wrapper.
final class AppSettings {
static let shared = AppSettings()
@FoilDefaultStorage(key: "flagEnabled")
var flagEnabled = true
@FoilDefaultStorage(key: "totalCount")
var totalCount = 0
@FoilDefaultStorageOptional(key: "timestamp")
var timestamp: Date?
}
// Usage
func userDidToggleSetting(_ sender: UISwitch) {
AppSettings.shared.flagEnabled = sender.isOn
}
There is also an included example app project.
enum
keys
Using If you prefer using an enum
for the keys, writing an extension specific to your app is easy. However, this is not required. In fact, unless you have a specific reason to reference the keys, this is completely unnecessary.
enum AppSettingsKey: String, CaseIterable {
case flagEnabled
case totalCount
case timestamp
}
extension FoilDefaultStorage {
init(wrappedValue: T, _ key: AppSettingsKey) {
self.init(wrappedValue: wrappedValue, key: key.rawValue)
}
}
extension FoilDefaultStorageOptional {
init(_ key: AppSettingsKey) {
self.init(key: key.rawValue)
}
}
Observing changes
There are many ways to observe property changes. The most common are by using Key-Value Observing or a Combine Publisher. KVO observing requires the object with the property to inherit from NSObject
and the property must be declared as @objc dynamic
.
final class AppSettings: NSObject {
static let shared = AppSettings()
@FoilDefaultStorageOptional(key: "userId")
@objc dynamic var userId: String?
@FoilDefaultStorageOptional(key: "average")
var average: Double?
}
Using KVO
let observer = AppSettings.shared.observe(\.userId, options: [.new]) { settings, change in
print(change)
}
Using Combine
Note
The average
does not need the @objc dynamic
annotation, .receiveValue
will fire immediately with the current value of average
and on every change after.
AppSettings.shared.$average
.sink {
print($0)
}
.store(in: &cancellable)
Combine Alternative with KVO
Note
In this case, userId
needs the @objc dynamic
annotation and AppSettings
needs to inherit from NSObject
. Then receiveValue
will fire only on changes to wrapped object's value. It will not publish the initial value as in the example above.
AppSettings.shared
.publisher(for: \.userId, options: [.new])
.sink {
print($0)
}
.store(in: &cancellable)
Supported types
The following types are supported by default for use with @FoilDefaultStorage
.
Important
Adding support for custom types is possible by conforming to UserDefaultsSerializable
. However, this is highly discouraged as all plist
types are supported by default. UserDefaults
is not intended for storing complex data structures and object graphs. You should probably be using a proper database (or serializing to disk via Codable
) instead.
While Foil
supports storing Codable
types by default, you should use this sparingly and only for small objects with few properties.
Bool
Int
UInt
Float
Double
String
URL
Date
Data
Array
Set
Dictionary
RawRepresentable
typesCodable
types
Warning
If you are storing custom Codable
types and using the default implementation of UserDefaultsSerializable
provided by Foil
, then you must use the optional variant of the property wrapper, @FoilDefaultStorageOptional
. This will allow you to make breaking changes to your Codable
type (e.g., adding or removing a property). Alternatively, you can provide a custom implementation of Codable
that supports migration, or provide a custom implementation of UserDefaultsSerializable
that handles encoding/decoding failures. See the example below.
Codable Example:
// Note: uses the default implementation of UserDefaultsSerializable
struct User: Codable, UserDefaultsSerializable {
let id: UUID
let name: String
}
// Yes, do this
@FoilDefaultStorageOptional(key: "user")
var user: User?
// NO, do NOT this
// This will crash if you change User by adding/removing properties
@FoilDefaultStorage(key: "user")
var user = User()
Additional Resources
- NSUserDefaults in Practice, the excellent guide by David Smith
- UserDefaults documentation
- Preferences and Settings Programming Guide
- Property List Programming Guide
Supported Platforms
- iOS 13.0+
- tvOS 13.0+
- watchOS 6.0+
- macOS 11+
Requirements
- Swift 5.9+
- Xcode 15.0+
- SwiftLint
Installation
CocoaPods
pod 'Foil', '~> 5.0.0'
Swift Package Manager
dependencies: [
.package(url: "https://github.com/jessesquires/Foil.git", from: "5.0.0")
]
Alternatively, you can add the package directly via Xcode.
Documentation
You can read the documentation here. Generated with jazzy. Hosted by GitHub Pages.
Contributing
Interested in making contributions to this project? Please review the guides below.
Also consider sponsoring this project or buying my apps! ✌️
Credits
Created and maintained by Jesse Squires.
License
Released under the MIT License. See LICENSE
for details.
Copyright © 2021-present Jesse Squires.