5 Useful Property Wrappers in Swift

Introduced in Swift 5.1, property wrappers quickly became one of the most heavily used features in all things Swift-related. All famous now SwiftUI framework could not have probably been the way it is now without its @State, @Binding, @StateObject and other black magic pieces you use every day. Or maybe you heard or even used one of the most popular object relational mapper frameworks (ORM) for a server side Swift’s Vapor called Fluent. They leave you with no choice to figure out how and when to use a dollar sign $ before a property neatly wrapped in yet another wrapper. The truth is that property wrappers are not that hard to crack when you dive deep and try to use them on your own. In fact, you might probably have a bunch of places in your project where you can get things easier by bringing a wrapper to help. In this guide I’ll cover 5 basic use cases like that. But first, let’s refresh our memories on the subject itself. What is a property wrapper? A property wrapper is a specially annotated type that encapsulates a piece of logic applied to any properties in general or properties constrained to some specific type you choose. It can be a struct, enum or class that declared with a @propertyWrapper attribute and has at least a wrappedValue as a mandatory property inside: @propertyWrapper struct SomeWrapper { var wrappedValue: T { // mandatory property get { value } set { value = newValue } } private var value: T init(wrappedValue: T) { self.value = wrappedValue } } Inside both a getter and a setter of the wrapped value property you can add any logic you need and intercept, transform or use values in basically any way you want. Then you can use the wrapper like this: class SomeService { @SomeWrapper fancyNumber: Int init(number: Int) { self._number = SomeWrapper(wrappedValue: number) // use "_" to initialize a property wrapper } func doSmth() { print(fancyNumber) } } What’s nice about property wrappers is that you can add your own initializers, additional methods, properties, etc. that may have any functionality you need. One of this is an optional projectedValue property that can return even a wrapper itself or any other type. Now, remember: when you want to access something that belongs to the wrapper itself, but not to its value, you need to use a notorious dollar sign: @propertyWrapper struct SomeWrapper { var wrappedValue: T { get { value } set { value = newValue } } private var value: T init(wrappedValue: T) { self.value = wrappedValue } func methodToDoSmth() { ... } // extra wrapper method } class SomeService { ... func doSmth() { $fancyNumber.methodToDoSmth() // here we access the logic of the wrapper itself } } Of course, all nonsensical examples above do not demonstrate true power of property wrappers enough, so let’s take a look at some of the most useful ways to make them shine. 1. Storage Inspired by all the things Fluent can do, we can apply property wrappers to deal with UserDefaults instead of creating a separate service for it this way: @propertyWrapper struct DefaultsStorage { private let key: String private let defaultValue: T init(key: String, defaultValue: T) { self.key = key self.defaultValue = defaultValue } var wrappedValue: T { get { // getting and decodind the data from UserDefaults guard let data = UserDefaults.standard.object(forKey: key) as? Data, let value = try? JSONDecoder().decode(T.self, from: data) else { return defaultValue } return value } set { // encodind the data and saving to UserDefaults guard let encoded = try? JSONEncoder().encode(newValue) else { return } let defaults = UserDefaults.standard defaults.set(encoded, forKey: key) } } } As you can see, the wrapper above can be used with anything Codable @DefaultsStorage(key: "upload_date", defaultValue: Date()) var uploadDate: Date The implementation above can be tweaked and changed a lot depending on your needs. For example, you can make it truly versatile by accepting other types or allow to use suite-based UserDefaults instead of the from-the-box standard singleton. Another thing is the data you save with it. If you want to store something securely, you may want to write a similar solution for Keychain. By the way, Apple already has a similar wrapper called @AppStorage, but it was designed to be used with SwiftUI which you might not necessarily want. 2. Logging In cases where you need to monitor a specific value, the following property wrapper can be useful for you: @propertyWrapper struct Logged { private var value: Value private let label: String // label that will be used in the log event init(wrappedValue: Value, label: String) { self.value = wrappedValue self.label = label print("\(label): Initial value set to \(value)") } var wrappedValue: Value { get { value } set { // prints the set event to a console print("\(label): Value changed from \(value) to \(newValue)") value = newValue } } } @Logged(label: "Total Price") var price = Double(12.5) This property wrapper might become even more useful with additional analytics service injected. It can be something local or even remote. If using the latter, remember to filter at the call site of such service to avoid unnecessary calls. 3. Validation We often need to validate user’s input. There are so many possible input types, like email, a phone number, birth date and so on. All of these require specific logic piece applied to original data. You can solve this by using a property wrapper for every input: @propertyWrapper struct ValidatedEmail { var value: Value? var wrappedValue: Value? { get { return validate(email: value) ? value : nil } set { value = newValue } } init(wrappedValue value: Value?) { self.value = value } private func validate(email: Value?) -> Bool { guard let email else { return false } let emailRegEx = "[A-Z0-9a-z._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,64}" let emailPred = NSPredicate(format:"SELF MATCHES %@", emailRegEx) return emailPred.evaluate(with: email) } } Or you can even try one-size-fits-all solution like this: @propertyWrapper struct Validated { // define all the possible inputs enum InputType { case email case phoneNumber ... } let inputType: InputType var value: Value? var wrappedValue: Value? { get { // return value if validation succeeds or nil if not return validate(value) ? value : nil } set { value = newValue } } init(inputType: InputType, wrappedValue value: Value?) { self.inputType = inputType self.value = value } private func validate(_ value: Value?) -> Bool { // include validation logic for every input type switch inputType { case .email: ... case .phoneNumber: ... } } } Similar to validating things, you can format dates with property wrappers by defining a set of prefixed formats you’d use inside the wrapper. 4. Clamped Sometimes you need to limit a value in a certain range, for example having percentage spanning from 0 to 100 or a fraction value from 0 to 1 and so on. You can encapsulate this logic in a property wrapper, too: @propertyWrapper struct Clamped { private var value: Value private let range: ClosedRange init(wrappedValue: Value, _ range: ClosedRange ) { self.range = range self.value = min(max(wrappedValue, range.lowerBound), range.upperBound) } var wrappedValue: Value { get { value } set { value = min(max(newValue, range.lowerBound), range.upperBound) } } } You can use it like this: struct ClampedExample { @Clamped(0...10) var number: Int init(number: Int) { self._number = Clamped(wrappedValue: number, 0...10) } func clampTest() { number = 20 print(example.number) // 10, because 20 is clamped to the upper bound 10 number = -5 print(example.number) // 0, because -5 is clamped to the lower bound 0 } } 5. Base64Encoding Another use case for property wrappers is to help us out with all things Codable. Custom encoding and decoding logic implementation can be safely put inside a wrapper if needed. You can also automatically encode a String into base64 with this simple solution: @propertyWrapper struct Base64Encoding { private var value = "" var wrappedValue: String { get { Data(value.utf8).base64EncodedString() } set { value = newValue } } } Using the wrapper above, whenever you access the text transformed by it, it will always return a base64 encoded string. Misuse of property wrappers However, when dealing with property wrappers, do not forget that they are same base Swift types we’ve known for years, but with added extra feature on top. One of many popular ideas on how to use a property wrapper back in the past was to try to thread-safe properties with it. You can find multiple implementations of @Atomic online, but it turned out that most of them are quite problematic. Even though fixes also can be found for it, I don’t recommend using @Atomic anymore, especially with actors now available to serve this purpose. Conclusion I hope that you learned a lot or at least refreshed your knowledge of property wrappers in Swift. With this refresher take a look at your current projects: maybe you have some pieces that can leverage the power of this feature! Introduced in Swift 5.1, property wrappers quickly became one of the most heavily used features in all things Swift-related. All famous now SwiftUI framework could not have probably been the way it is now without its @State , @Binding , @StateObject and other black magic pieces you use every day. Or maybe you heard or even used one of the most popular object relational mapper frameworks (ORM) for a server side Swift’s Vapor called Fluent . They leave you with no choice to figure out how and when to use a dollar sign $ before a property neatly wrapped in yet another wrapper. @State @Binding @StateObject Vapor Fluent $ The truth is that property wrappers are not that hard to crack when you dive deep and try to use them on your own. In fact, you might probably have a bunch of places in your project where you can get things easier by bringing a wrapper to help. In this guide I’ll cover 5 basic use cases like that. But first, let’s refresh our memories on the subject itself. What is a property wrapper? A property wrapper is a specially annotated type that encapsulates a piece of logic applied to any properties in general or properties constrained to some specific type you choose. It can be a struct, enum or class that declared with a @propertyWrapper attribute and has at least a wrappedValue as a mandatory property inside: @propertyWrapper wrappedValue @propertyWrapper struct SomeWrapper { var wrappedValue: T { // mandatory property get { value } set { value = newValue } } private var value: T init(wrappedValue: T) { self.value = wrappedValue } } @propertyWrapper struct SomeWrapper { var wrappedValue: T { // mandatory property get { value } set { value = newValue } } private var value: T init(wrappedValue: T) { self.value = wrappedValue } } Inside both a getter and a setter of the wrapped value property you can add any logic you need and intercept, transform or use values in basically any way you want. Then you can use the wrapper like this: class SomeService { @SomeWrapper fancyNumber: Int init(number: Int) { self._number = SomeWrapper(wrappedValue: number) // use "_" to initialize a property wrapper } func doSmth() { print(fancyNumber) } } class SomeService { @SomeWrapper fancyNumber: Int init(number: Int) { self._number = SomeWrapper(wrappedValue: number) // use "_" to initialize a property wrapper } func doSmth() { print(fancyNumber) } } What’s nice about property wrappers is that you can add your own initializers, additional methods, properties, etc. that may have any functionality you need. One of this is an optional projectedValue property that can return even a wrapper itself or any other type. Now, remember: when you want to access something that belongs to the wrapper itself, but not to its value, you need to use a notorious dollar sign: projectedValue @propertyWrapper struct SomeWrapper { var wrappedValue: T { get { value } set { value = newValue } } private var value: T init(wrappedValue: T) { self.value = wrappedValue } func methodToDoSmth() { ... } // extra wrapper method } class SomeService { ... func doSmth() { $fancyNumber.methodToDoSmth() // here we access the logic of the wrapper itself } } @propertyWrapper struct SomeWrapper { var wrappedValue: T { get { value } set { value = newValue } } private var value: T init(wrappedValue: T) { self.value = wrappedValue } func methodToDoSmth() { ... } // extra wrapper method } class SomeService { ... func doSmth() { $fancyNumber.methodToDoSmth() // here we access the logic of the wrapper itself } } Of course, all nonsensical examples above do not demonstrate true power of property wrappers enough, so let’s take a look at some of the most useful ways to make them shine. 1. Storage Inspired by all the things Fluent can do, we can apply property wrappers to deal with UserDefaults instead of creating a separate service for it this way: UserDefaults @propertyWrapper struct DefaultsStorage { private let key: String private let defaultValue: T init(key: String, defaultValue: T) { self.key = key self.defaultValue = defaultValue } var wrappedValue: T { get { // getting and decodind the data from UserDefaults guard let data = UserDefaults.standard.object(forKey: key) as? Data, let value = try? JSONDecoder().decode(T.self, from: data) else { return defaultValue } return value } set { // encodind the data and saving to UserDefaults guard let encoded = try? JSONEncoder().encode(newValue) else { return } let defaults = UserDefaults.standard defaults.set(encoded, forKey: key) } } } @propertyWrapper struct DefaultsStorage { private let key: String private let defaultValue: T init(key: String, defaultValue: T) { self.key = key self.defaultValue = defaultValue } var wrappedValue: T { get { // getting and decodind the data from UserDefaults guard let data = UserDefaults.standard.object(forKey: key) as? Data, let value = try? JSONDecoder().decode(T.self, from: data) else { return defaultValue } return value } set { // encodind the data and saving to UserDefaults guard let encoded = try? JSONEncoder().encode(newValue) else { return } let defaults = UserDefaults.standard defaults.set(encoded, forKey: key) } } } As you can see, the wrapper above can be used with anything Codable Codable @DefaultsStorage(key: "upload_date", defaultValue: Date()) var uploadDate: Date @DefaultsStorage(key: "upload_date", defaultValue: Date()) var uploadDate: Date The implementation above can be tweaked and changed a lot depending on your needs. For example, you can make it truly versatile by accepting other types or allow to use suite-based UserDefaults instead of the from-the-box standard singleton. UserDefaults standard Another thing is the data you save with it. If you want to store something securely, you may want to write a similar solution for Keychain. By the way, Apple already has a similar wrapper called @AppStorage , but it was designed to be used with SwiftUI which you might not necessarily want. @AppStorage 2. Logging In cases where you need to monitor a specific value, the following property wrapper can be useful for you: @propertyWrapper struct Logged { private var value: Value private let label: String // label that will be used in the log event init(wrappedValue: Value, label: String) { self.value = wrappedValue self.label = label print("\(label): Initial value set to \(value)") } var wrappedValue: Value { get { value } set { // prints the set event to a console print("\(label): Value changed from \(value) to \(newValue)") value = newValue } } } @propertyWrapper struct Logged { private var value: Value private let label: String // label that will be used in the log event init(wrappedValue: Value, label: String) { self.value = wrappedValue self.label = label print("\(label): Initial value set to \(value)") } var wrappedValue: Value { get { value } set { // prints the set event to a console print("\(label): Value changed from \(value) to \(newValue)") value = newValue } } } @Logged(label: "Total Price") var price = Double(12.5) @Logged(label: "Total Price") var price = Double(12.5) This property wrapper might become even more useful with additional analytics service injected. It can be something local or even remote. If using the latter, remember to filter at the call site of such service to avoid unnecessary calls. 3. Validation We often need to validate user’s input. There are so many possible input types, like email, a phone number, birth date and so on. All of these require specific logic piece applied to original data. You can solve this by using a property wrapper for every input: @propertyWrapper struct ValidatedEmail { var value: Value? var wrappedValue: Value? { get { return validate(email: value) ? value : nil } set { value = newValue } } init(wrappedValue value: Value?) { self.value = value } private func validate(email: Value?) -> Bool { guard let email else { return false } let emailRegEx = "[A-Z0-9a-z._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,64}" let emailPred = NSPredicate(format:"SELF MATCHES %@", emailRegEx) return emailPred.evaluate(with: email) } } @propertyWrapper struct ValidatedEmail { var value: Value? var wrappedValue: Value? { get { return validate(email: value) ? value : nil } set { value = newValue } } init(wrappedValue value: Value?) { self.value = value } private func validate(email: Value?) -> Bool { guard let email else { return false } let emailRegEx = "[A-Z0-9a-z._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,64}" let emailPred = NSPredicate(format:"SELF MATCHES %@", emailRegEx) return emailPred.evaluate(with: email) } } Or you can even try one-size-fits-all solution like this: @propertyWrapper struct Validated { // define all the possible inputs enum InputType { case email case phoneNumber ... } let inputType: InputType var value: Value? var wrappedValue: Value? { get { // return value if validation succeeds or nil if not return validate(value) ? value : nil } set { value = newValue } } init(inputType: InputType, wrappedValue value: Value?) { self.inputType = inputType self.value = value } private func validate(_ value: Value?) -> Bool { // include validation logic for every input type switch inputType { case .email: ... case .phoneNumber: ... } } } @propertyWrapper struct Validated { // define all the possible inputs enum InputType { case email case phoneNumber ... } let inputType: InputType var value: Value? var wrappedValue: Value? { get { // return value if validation succeeds or nil if not return validate(value) ? value : nil } set { value = newValue } } init(inputType: InputType, wrappedValue value: Value?) { self.inputType = inputType self.value = value } private func validate(_ value: Value?) -> Bool { // include validation logic for every input type switch inputType { case .email: ... case .phoneNumber: ... } } } Similar to validating things, you can format dates with property wrappers by defining a set of prefixed formats you’d use inside the wrapper. 4. Clamped Sometimes you need to limit a value in a certain range, for example having percentage spanning from 0 to 100 or a fraction value from 0 to 1 and so on. You can encapsulate this logic in a property wrapper, too: @propertyWrapper struct Clamped { private var value: Value private let range: ClosedRange init(wrappedValue: Value, _ range: ClosedRange ) { self.range = range self.value = min(max(wrappedValue, range.lowerBound), range.upperBound) } var wrappedValue: Value { get { value } set { value = min(max(newValue, range.lowerBound), range.upperBound) } } } @propertyWrapper struct Clamped { private var value: Value private let range: ClosedRange init(wrappedValue: Value, _ range: ClosedRange ) { self.range = range self.value = min(max(wrappedValue, range.lowerBound), range.upperBound) } var wrappedValue: Value { get { value } set { value = min(max(newValue, range.lowerBound), range.upperBound) } } } You can use it like this: struct ClampedExample { @Clamped(0...10) var number: Int init(number: Int) { self._number = Clamped(wrappedValue: number, 0...10) } func clampTest() { number = 20 print(example.number) // 10, because 20 is clamped to the upper bound 10 number = -5 print(example.number) // 0, because -5 is clamped to the lower bound 0 } } struct ClampedExample { @Clamped(0...10) var number: Int init(number: Int) { self._number = Clamped(wrappedValue: number, 0...10) } func clampTest() { number = 20 print(example.number) // 10, because 20 is clamped to the upper bound 10 number = -5 print(example.number) // 0, because -5 is clamped to the lower bound 0 } } 5. Base64Encoding Another use case for property wrappers is to help us out with all things Codable . Custom encoding and decoding logic implementation can be safely put inside a wrapper if needed. You can also automatically encode a String into base64 with this simple solution: Codable @propertyWrapper struct Base64Encoding { private var value = "" var wrappedValue: String { get { Data(value.utf8).base64EncodedString() } set { value = newValue } } } @propertyWrapper struct Base64Encoding { private var value = "" var wrappedValue: String { get { Data(value.utf8).base64EncodedString() } set { value = newValue } } } Using the wrapper above, whenever you access the text transformed by it, it will always return a base64 encoded string. Misuse of property wrappers However, when dealing with property wrappers, do not forget that they are same base Swift types we’ve known for years, but with added extra feature on top. One of many popular ideas on how to use a property wrapper back in the past was to try to thread-safe properties with it. You can find multiple implementations of @Atomic online, but it turned out that most of them are quite problematic . Even though fixes also can be found for it, I don’t recommend using @Atomic anymore, especially with actors now available to serve this purpose. @Atomic but it turned out that most of them are quite problematic @Atomic Conclusion I hope that you learned a lot or at least refreshed your knowledge of property wrappers in Swift. With this refresher take a look at your current projects: maybe you have some pieces that can leverage the power of this feature!