{"id":13995032,"url":"https://github.com/jessesquires/Foil","last_synced_at":"2025-07-22T21:31:50.296Z","repository":{"id":41867033,"uuid":"332649826","full_name":"jessesquires/Foil","owner":"jessesquires","description":"A lightweight property wrapper for UserDefaults done right","archived":false,"fork":false,"pushed_at":"2024-10-04T22:13:12.000Z","size":460,"stargazers_count":459,"open_issues_count":1,"forks_count":26,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-11-20T10:56:00.007Z","etag":null,"topics":["foil","ios","macos","property-wrapper","swift","tvos","userdefaults","watchos"],"latest_commit_sha":null,"homepage":"https://jessesquires.github.io/Foil/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jessesquires.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-25T06:19:07.000Z","updated_at":"2024-11-10T10:36:30.000Z","dependencies_parsed_at":"2024-01-25T23:16:46.067Z","dependency_job_id":"78b6872e-4f0b-4691-9ab9-7ef1d94cfaa5","html_url":"https://github.com/jessesquires/Foil","commit_stats":{"total_commits":200,"total_committers":9,"mean_commits":22.22222222222222,"dds":0.5349999999999999,"last_synced_commit":"ff4b49d2e7852f876ded552fb596e510a66670b9"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessesquires%2FFoil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessesquires%2FFoil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessesquires%2FFoil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jessesquires%2FFoil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jessesquires","download_url":"https://codeload.github.com/jessesquires/Foil/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227177740,"owners_count":17743154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["foil","ios","macos","property-wrapper","swift","tvos","userdefaults","watchos"],"created_at":"2024-08-09T14:03:13.227Z","updated_at":"2024-11-29T17:30:54.102Z","avatar_url":"https://github.com/jessesquires.png","language":"Swift","funding_links":["https://github.com/sponsors/jessesquires"],"categories":["Swift"],"sub_categories":[],"readme":"# Foil [![Actions Status](https://github.com/jessesquires/Foil/workflows/CI/badge.svg)](https://github.com/jessesquires/Foil/actions)\n\n*A lightweight [property wrapper](https://docs.swift.org/swift-book/ReferenceManual/Attributes.html#ID348) for UserDefaults done right*\n\n[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fjessesquires%2FFoil%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/jessesquires/Foil) \u003cbr\u003e [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fjessesquires%2FFoil%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/jessesquires/Foil)\n\n## About\n\nRead the post: [A better approach to writing a UserDefaults Property Wrapper](https://www.jessesquires.com/blog/2021/03/26/a-better-approach-to-writing-a-userdefaults-property-wrapper/)\n\n#### Why the name?\n\nFoil, as in \"let me quickly and easily **wrap** and **store** this leftover food in some **foil** so I can eat it later.\" 🌯 😉\n\n\u003e [Foil](https://www.wordnik.com/words/aluminum%20foil):\u003cbr\u003e\n\u003e **noun**\u003cbr\u003e\n\u003e *North America*\u003cbr\u003e\n\u003e A very thin, pliable, easily torn sheet of aluminum used for cooking, packaging, cosmetics, and insulation.\n\n## Usage\n\nYou can use `@FoilDefaultStorage` for non-optional values and `@FoilDefaultStorageOptional` for optional ones.\nYou 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.\n\n```swift\nfinal class AppSettings {\n    static let shared = AppSettings()\n\n    @FoilDefaultStorage(key: \"flagEnabled\")\n    var flagEnabled = true\n\n    @FoilDefaultStorage(key: \"totalCount\")\n    var totalCount = 0\n\n    @FoilDefaultStorageOptional(key: \"timestamp\")\n    var timestamp: Date?\n}\n\n// Usage\n\nfunc userDidToggleSetting(_ sender: UISwitch) {\n    AppSettings.shared.flagEnabled = sender.isOn\n}\n```\n\nThere is also an included example app project.\n\n### Using `enum` keys\n\nIf 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.\n\n```swift\nenum AppSettingsKey: String, CaseIterable {\n    case flagEnabled\n    case totalCount\n    case timestamp\n}\n\nextension FoilDefaultStorage {\n    init(wrappedValue: T, _ key: AppSettingsKey) {\n        self.init(wrappedValue: wrappedValue, key: key.rawValue)\n    }\n}\n\nextension FoilDefaultStorageOptional {\n    init(_ key: AppSettingsKey) {\n        self.init(key: key.rawValue)\n    }\n}\n```\n\n### Observing changes\n\nThere are [many ways to observe property changes](https://www.jessesquires.com/blog/2021/08/08/different-ways-to-observe-properties-in-swift/). 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`.\n\n```swift\nfinal class AppSettings: NSObject {\n    static let shared = AppSettings()\n\n    @FoilDefaultStorageOptional(key: \"userId\")\n    @objc dynamic var userId: String?\n\n    @FoilDefaultStorageOptional(key: \"average\")\n    var average: Double?\n}\n```\n\n#### Using KVO\n\n```swift\nlet observer = AppSettings.shared.observe(\\.userId, options: [.new]) { settings, change in\n    print(change)\n}\n```\n\n#### Using Combine\n\n\u003e [!NOTE]\n\u003e The `average` does not need the `@objc dynamic` annotation, `.receiveValue` will fire immediately with the current value of `average` and on every change after.\n\n```swift\nAppSettings.shared.$average\n    .sink {\n        print($0)\n    }\n    .store(in: \u0026cancellable)\n```\n\n#### Combine Alternative with KVO\n\n\u003e [!NOTE]\n\u003e 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.\n\n```swift\nAppSettings.shared\n    .publisher(for: \\.userId, options: [.new])\n    .sink {\n        print($0)\n    }\n    .store(in: \u0026cancellable)\n```\n\n### Supported types\n\nThe following types are supported by default for use with `@FoilDefaultStorage`.\n\n\u003e [!NOTE]\n\u003e While the `UserDefaultsSerializable` protocol defines a _failable_ initializer, `init?(storedValue:)`, it is possible to provide a custom implementation with a **non-failable** initializer, which still satisfies the protocol requirements.\n\u003e\n\u003e For all of Swift's built-in types (`Bool`, `Int`, `Double`, `String`, etc.), the default implementation of `UserDefaultsSerializable` is **non-failable**.\n\n\u003e [!IMPORTANT]\n\u003e 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.\n\u003e\n\u003e While `Foil` supports storing `Codable` types by default, you should **use this sparingly** and _only_ for small objects with few properties.\n\n- `Bool`\n- `Int`\n- `UInt`\n- `Float`\n- `Double`\n- `String`\n- `URL`\n- `Date`\n- `Data`\n- `Array`\n- `Set`\n- `Dictionary`\n- `RawRepresentable` types\n- `Codable` types\n\n#### Notes on [`Codable`](https://developer.apple.com/documentation/swift/codable) types\n\n\u003e [!WARNING]\n\u003e 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.\n\n**Codable Example:**\n```swift\n// Note: uses the default implementation of UserDefaultsSerializable\nstruct User: Codable, UserDefaultsSerializable {\n    let id: UUID\n    let name: String\n}\n\n// Yes, do this\n@FoilDefaultStorageOptional(key: \"user\")\nvar user: User?\n\n// NO, do NOT this\n// This will crash if you change User by adding/removing properties\n@FoilDefaultStorage(key: \"user\")\nvar user = User()\n```\n\n#### Notes on [`RawRepresentable`](https://developer.apple.com/documentation/swift/rawrepresentable) types\n\nUsing `RawRepresentable` types, especially as properties of a `Codable` type require special considerations. As mentioned above, `Codable` types must use `@FoilDefaultStorageOptional` out-of-the-box, unless you provide a custom implementation of `UserDefaultsSerializable`. The same is true for `RawRepresentable` types.\n\n\u003e [!WARNING]\n\u003e `RawRepresentable` types must use `@FoilDefaultStorageOptional` in case you modify the cases of your `enum` (or otherwise modify your `RawRepresentable` with a breaking change). Additionally, `RawRepresentable` types have a designated initializer that is failable, `init?(rawValue:)`, and thus could return `nil`.\n\u003e\n\u003e Or, if you are storing a `Codable` type that has `RawRepresentable` properties, by default those properties should be optional to accommodate the optionality described above.\n\nIf you wish to avoid these edge cases with `RawRepresentable` types, you can provide a non-failable initializer:\n\n```swift\nextension MyStringEnum: UserDefaultsSerializable {\n    // Default init provided by Foil\n    // public init?(storedValue: RawValue.StoredValue) { ... }\n\n    // New, non-failable init using force-unwrap.\n    // Only do this if you know you will not make breaking changes.\n    public init(storedValue: String) { self.init(rawValue: storedValue)! }\n}\n```\n\n## Additional Resources\n\n- [NSUserDefaults in Practice](http://dscoder.com/defaults.html), the excellent guide by [David Smith](https://twitter.com/Catfish_Man)\n- [UserDefaults documentation](https://developer.apple.com/documentation/foundation/userdefaults)\n- [Preferences and Settings Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/UserDefaults/Introduction/Introduction.html#//apple_ref/doc/uid/10000059i-CH1-SW1)\n- [Property List Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/Introduction/Introduction.html#//apple_ref/doc/uid/10000048i)\n\n## Supported Platforms\n\n- iOS 13.0+\n- tvOS 13.0+\n- watchOS 6.0+\n- macOS 11.0+\n- visionOS 1.0+\n\n## Requirements\n\n- Swift 6.0+\n- Xcode 16.0+\n- [SwiftLint](https://github.com/realm/SwiftLint)\n\n## Installation\n\n### [Swift Package Manager](https://swift.org/package-manager/)\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/jessesquires/Foil.git\", from: \"6.0.0\")\n]\n```\n\nAlternatively, you can add the package [directly via Xcode](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app).\n\n## Documentation\n\nYou can read the [documentation here](https://jessesquires.github.io/Foil). Generated with [jazzy](https://github.com/realm/jazzy). Hosted by [GitHub Pages](https://pages.github.com).\n\nDocumentation is also available on the [Swift Package Index](https://swiftpackageindex.com/jessesquires/Foil/documentation).\n\n## Contributing\n\nInterested in making contributions to this project? Please review the guides below.\n\n- [Contributing Guidelines](https://github.com/jessesquires/.github/blob/main/CONTRIBUTING.md)\n- [Code of Conduct](https://github.com/jessesquires/.github/blob/main/CODE_OF_CONDUCT.md)\n- [Support and Help](https://github.com/jessesquires/.github/blob/main/SUPPORT.md)\n- [Security Policy](https://github.com/jessesquires/.github/blob/main/SECURITY.md)\n\nAlso consider [sponsoring this project](https://github.com/sponsors/jessesquires) or [buying my apps](https://www.hexedbits.com)! ✌️\n\n## Credits\n\nCreated and maintained by [**Jesse Squires**](https://www.jessesquires.com).\n\n## License\n\nReleased under the MIT License. See `LICENSE` for details.\n\n\u003e **Copyright \u0026copy; 2021-present Jesse Squires.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjessesquires%2FFoil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjessesquires%2FFoil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjessesquires%2FFoil/lists"}