Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/onmyway133/EasyStash
🗳Easy data persistence in Swift
https://github.com/onmyway133/EasyStash
cache codable disk image load save storage swift
Last synced: 3 months ago
JSON representation
🗳Easy data persistence in Swift
- Host: GitHub
- URL: https://github.com/onmyway133/EasyStash
- Owner: onmyway133
- License: other
- Created: 2019-05-27T10:40:48.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-05-09T15:22:07.000Z (9 months ago)
- Last Synced: 2024-10-25T06:02:08.168Z (3 months ago)
- Topics: cache, codable, disk, image, load, save, storage, swift
- Language: Swift
- Homepage: https://onmyway133.com
- Size: 105 KB
- Stars: 378
- Watchers: 6
- Forks: 23
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
- awesome - EasyStash - 🗳Easy data persistence in Swift (swift)
- awesome - EasyStash - 🗳Easy data persistence in Swift (save)
README
# Easy Stash
- [Blog](https://onmyway133.com/)
- [Apps](https://indiegoodies.com)
[](https://circleci.com/gh/onmyway133/EasyStash)
[](http://cocoadocs.org/docsets/EasyStash)
[](https://github.com/Carthage/Carthage)
[](https://github.com/apple/swift-package-manager)
[](http://cocoadocs.org/docsets/EasyStash)
[](http://cocoadocs.org/docsets/EasyStash)
## Description
EasyStash is an easy and lightweight persistence framework in Swift. With simple abstraction over `NSCache` and `FileManager`, it saves us from tedious work of saving and loading objects. There are no clever async, expiry handling or caching strategy for now, just save and load.
- [x] Swift 5
- [x] Support iOS, macOS, tvOS, watchOS
- [x] Synchronous APIs with explicit try catch
- [x] Persist UIImage/NSImage
- [x] Persist Codable objects, including primitive types
- [x] Persist Data
- [x] Test coverage
## Usage
The main and only class is `Storage` which encapsulates memory and disk cache. All operations involving disk are error prone, we need to handle error explicitly.
With `Options`, we can customize `folder` name, `searchPathDirectory`, `encoder` and `decoder` for `Codable`. By default, `folder` and `searchPathDirectory` specify that files will be saved at `/Library/Application Support/{BUNDLE_ID}/Default/`
```swift
var storage: Storage? = nil
var options: Options = Options()
options.folder = "Users"
storage = try? Storage(options: options)
do {
try storage?.save(image, forKey: "image")
try storage?.save(users, forKey: "codable")
} catch {
print(error)
}
```
Memory cache is checked first before doing disk operations, so we won't hit disk that often.
### Saving and loading images
Works for both UIImage and NSImage. Because image and data loading uses the same signatures, we need to explicitly specify type
```swift
try storage.save(image, forKey: "image")
let loadedImage: UIImage = try storage.load(forKey: "image")
```
### Saving and loading Codable objects
Uses `JSONEncoder` and `JSONDecoder` under the hood to serialize and deserialize to and from `Data`
```swift
let user = User(name: "A", age: 10)
let cities = [City(name: "Oslo"), City(name: "New York")]
try storage.save(users, forKey: "user")
try storage.save(cities, forKey: "cities")
let loadedUser = try storage.load(forKey: "user", as: User.self)
let loadedCities = try storage.load(forKey: "cities", as: [City].self)
```
### Saving and loading Data
```swift
try storage.save(object: data, forKey: "data")
let loadedData: Data = try storage.load(forKey: "data")
```
### Saving and loading primitives
Although primitives like `Int, String, Bool` conform to `Codable`, they can't be serialized into `Data` using `JSONEncoder` because json needs root object. This framework handles this case, so you can just save and load as normal
```swift
try storage.save(100, forKey: "an int")
try storage.save(isLoggedIn, forKey: "a boolean")
```
### Folder informations
EasyStash includes some helpful functions to check file and folder within its `Storage`.
Check if file exists
```swift
try storage.exists(forKey: "has_updated_profile")
```
Remove file
```swift
try storage.remove(forKey: "a flag")
```
Remove all files
```swift
try storage.removeAll()
```
List all files. Each file has `name`, `url`, `modificationDate` and `size` information
```swift
let files = try storage.files()
```
Check folder size
```swift
let size = try storage.folderSize()
```
Check if folder has content
```swift
try storage.isEmpty()
```
Remove files based on predicate. This is useful when we want to clear expired objects, or objects based certain criteria.
```swift
try storage.removeAll(predicate: { $0.modificationDate < migrationDate })
```
## Async
`EasyStash` is designed to be synchronous. If we want to do async, it's easy as using `DispatchQueue`
```swift
DispatchQueue.global().async {
do {
try storage.save(largeImage, forKey: "large_image")
} catch {
}
}
```
## Installation
**EasyStash** is available through [CocoaPods](http://cocoapods.org). To install
it, simply add the following line to your Podfile:
```ruby
pod 'EasyStash'
```
**EasyStash** is also available through [Carthage](https://github.com/Carthage/Carthage).
To install just write into your Cartfile:
```ruby
github "onmyway133/EasyStash"
```
**EasyStash** is also available through [Swift Package Manager](https://swift.org/package-manager/).
Add EasyStash as a dependency to your Package.swift. For more information, please see the [Swift Package Manager documentation](https://github.com/apple/swift-package-manager/tree/master/Documentation).
```swift
.package(url: "https://github.com/onmyway133/EasyStash", from: "1.1.8")
```
**EasyStash** can also be installed manually. Just download and drop `Sources` folders in your project.
## Author
Khoa Pham, [email protected]
## Contributing
We would love you to contribute to **EasyStash**, check the [CONTRIBUTING](https://github.com/onmyway133/EasyStash/blob/master/CONTRIBUTING.md) file for more info.
## License
**EasyStash** is available under the MIT license. See the [LICENSE](https://github.com/onmyway133/EasyStash/blob/master/LICENSE.md) file for more info.