sunshinejr / SwiftyUserDefaults

SwiftyUserDefaults Modern Swift API for SwiftyUserDefaults makes user defaults enjoyable to use by combining expressive Swifty API with the benefits of static typing. Define your keys in one place, use value types easily, and get extra safety and convenient compile-time checks for free. Previous versions' documentation: Version 4.0.0, Version 3.0.1 Migration guides: from 4.x to 5.x, from 4.0.0-alpha.1 to 4.0.0-alpha.3, from 3.x to 4.x Version 5.0.0 Features • Usage • Codable • NSCoding • RawRepresentable • Extending existing types • Custom types Property wrappers • KVO • dynamicMemberLookup • Launch arguments • Utils • Installation Features **There's only one step to start using SwiftyUserDefaults:** Define your keys! And just use it ;-) If you use Swift 5.1 - good news! You can also use keyPath : See more at the KeyPath dynamicMemberLookup section. Usage Define your keys To get the most out of SwiftyUserDefaults, define your user defaults keys ahead of time: Just create a object, put the type of the value you want to store in angle brackets, the key name in parentheses, and you're good to go. If you want to have a non-optional value, just provide a in the key (look at the example above). You can now use the shortcut to access those values: The compiler won't let you set a wrong value type, and fetching conveniently returns . Take shortcuts For extra convenience, define your keys by extending magic class and adding static properties: And use the shortcut dot syntax: Supported types SwiftyUserDefaults supports all of the standard types, like strings, numbers, booleans, arrays and dictionaries. Here's a full table of built-in single value defaults: | Single value | Array | | ---------------- | -------------------- | | | | | | | | | | | | | | | | | | | | | | | | | But that's not all! Codable Since version 4, support ! Just conform to in your type: No implementation needed! By doing this you will get an option to specify an optional : Additionally, you've got an array support for free: NSCoding was supported before version 4, but in this version we take the support on another level. No need for custom subscripts anymore! Support your custom type the same way as with support: No implementation needed as well! By doing this you will get an option to specify an optional : Additionally, you've got an array support also for free: RawRepresentable And the last but not least, support! Again, the same situation like with and : No implementation needed as well! By doing this you will get an option to specify an optional : Additionally, you've got an array support also for free: Extending existing types Let's say you want to extend a support or any other type that is , or . Extending it to be -friendly should be as easy as: If it's not, we have two options: a) It's a custom type that we don't know how to serialize, in this case at Custom types b) It's a bug and it should be supported, in this case please file an issue (+ you can use custom types method as a workaround in the meantime) Custom types If you want to add your own custom type that we don't support yet, we've got you covered. We use s of many kinds to specify how you get/set values and arrays of values. When you look at protocol, it expects two properties in each type: and , where both are of type . For instance, this is a bridge for single value data storing/retrieving using / : Bridge for default storing/retrieving array values: Now, to use these bridges in our type we simply declare it as follows: Unfortunately, if you find yourself in a situation where you need a custom bridge, you'll probably need to write your own: To support existing types with different bridges, you can extend it similarly: Also, take a look at our source code (or tests) to see more examples of bridges. If you find yourself confused with all these bridges, please create an issue and we will figure something out. Property wrappers SwiftyUserDefaults provides property wrappers for Swift 5.1! The property wrapper, , provides an option to use it with key path and options: caching or observing. *Caching* means that we will store the value for you and do not hit the for value almost never, only for the first value fetch. *Observing* means we will observe, via KVO, your property so you don't have to worry if it was saved somewhere else and you use caching. Now usage! Given keys: You can declare a struct: KVO KVO is supported for all the types that are . However, if you have a custom type, it needs to have correctly defined bridges and serialization in them. To observe a value for local DefaultsKey: To observe a value for a key defined in DefaultsKeys extension: By default we are using options for observing, but you can provide your own: KeyPath dynamicMemberLookup SwiftyUserDefaults makes KeyPath dynamicMemberLookup usable in Swift 5.1! And just use it ;-) Launch arguments Do you like to customize your app/script/tests by UserDefaults? Now it's fully supported on our side, statically typed of course. _Note: for now we support only , , , values, but if you have any other requests for that feature, please open an issue or PR and we can talk about implementing it in new versions._ You can pass your arguments in your schema: Or you can use launch arguments in XCUIApplication: Or pass them as command line arguments! Utils Remove all keys To reset user defaults, use method. Shared user defaults If you're sharing your user defaults between different apps or an app and its extensions, you can use SwiftyUserDefaults by overriding the shortcut with your own. Just add in your app: Check key If you want to check if we've got a value for : Installation Requirements **Swift** version **>= 4.1** **iOS** version **>= 9.0** **macOS** version **>= 10.11** **tvOS** version **>= 9.0** **watchOS** version **>= 2.0** CocoaPods If you're using CocoaPo…