vexy/Fridge v0.9.3

Handle your structs like a boss 🧞‍♂️

⭐️ 13

🕓 1 year ago

iOS macOS tvOS

.package(url: "https://github.com/vexy/Fridge.git", from: "v0.9.3")

❄️ Fridge ❄️

Fridge - extremely simple async/await fetch-and-store implementation you'll ever see !
Let your fancy struct(s) raise and shine again, allowing you to focus on 💬 🥊🤖⭐️🗝 stuff.

💠 Library interface

Fridge is a freezing device ❄️. It has to keep things cool enough, exposing just icy interface.

Networking

Method	Description
`Fridge.grab🔮(from: URL)`	Grabs your model from the network endpoint (iOS 15+ only)
`Fridge.push📡(object, to)`	Pushes (sends) your model to designated network endpoint (iOS 15+ only)

Fridge networking model supports async/await philosophy and is here to reduce the pain of:

fetching your stuff from the network,
parsing or decoding (JSON) data,
doing boring error checking
and yeah... good old closures.

With Fridge, you can even say goodbye to closures and CoreData if you want! 🤷🏻‍♂️

Checkout documentation for more information.

Persistant (local) storage

Method	Description
`Fridge.freeze🧊(object, identifier)`	Safely "freezes" your `struct` to persistant store
`Fridge.unfreeze🪅🎉(identifier)`	"Unfreezes" (previously frozen), `struct` giving you control of it

Fridge storage mechanics are built on Foundation principles and use BSON as internal storage mechanism. All you have to do is to conform your struct to Encodable and you're ready to go, Fridge will take care of the rest.

Checkout documentation for more information.

Quick code example

// 1. Conform your fancy struct to Decodable
struct GHRepo: Decodable {
    var name: String
    var repositoryURL: URL
    // ... other fields
}

do {
  // 2. Await for grab🔮 method...
  let myRepo: GHRepo = try await Fridge.grab🔮(from: URL("https://github.com/vexy/")!)
} catch let err {
  print("Naaah.. Something bad happened: \(err)")
}

// 3. Then, at your will, use myRepo as any other Foundation object
print(myRepo)
print(myRepo.name)

// ... something ...

// 4. Later on...
do {
  try Fridge.freeze🧊(myRepo, id: "myIdentifier")
} catch let e {
  print("Whoops... Here: \(e)")
}

Talking is cheap. Show me the code. - Linus Torvalds

Here is some real world usage of Fridge:

Installation instructions

Using Swift Package Manager is by far the sexiest way to install Fridge.

// swift-tools-version:5.3
import PackageDescription

let package = Package(
    name: "YOUR-PACKAGE",
    dependencies: [
        .package(url: "https://github.com/vexy/Fridge.git", .upToNextMajor(from: "0.9"))
    ],
    targets: [
        .target(name: "YOUR-TARGET", dependencies: ["Fridge"])
    ]
)

Quick links:

name: "Fridge"
url: "https://github.com/vexy/Fridge.git"
branch: "main"

Minimum versions required

For Fridge to work in full capacity, following Swift & iOS configuration is recommended:

Xcode 13.1+
Swift 5.5
iOS 15.0+
macOS 12.0

Recommended versions mentioned above area guaranteed to successfully build & test Fridge ✅.
If nothing else, you can always fire an issue if you stumble upon the way.

Although, you can even run Fridge with following: 😮

iOS 11.0+
macOS 10.14

...but you won't be able to grab🔮 things nor any of the fancy async/await things. Sorry 🤷🏻‍♂️

NOTEs
Be sure to meet minimum configuration parameters as you may encounter difficult-to-recover build errors on earlier configurations.
Sometimes, setting liker flag to -Xfrontend -enable-experimental-concurrency helps, but may fail if building with commandline.
That may be helpfull for Xcode 12.x, assuming Swift 5.x is installed.

Checkout official Swift.org website, for supporting earlier than minimums and other info.

External dependencies

Fridge uses BSONCoder v0.9 - Copyright by Vexy.
Check original library licencing information under licencing section in README file.

Documentation

RTFM isn't a joke... 🥴

In the Docs you'll quickly figure out how to:

easily fetch object from the network,
persistently store your objects,
load them back into your app,
catch nasty errors along the way
all other dirtly little secrets about the Fridge

Check usage examples or entire Guides collection for more goodies.
Xcode Playground file can be found here. For a bigger picture overview, feel free to check architecture diagrams... ∰

Contribution guidelines

If you like Fridge, feel free to fire a pull request. The prefered way is to branch off the main branch, complete feature or a fix and then merge to development. After the pull request has been approved, your change will be merged to main.

Don't be affraid to start any discussions if you think so.
Issues section is a good way to start, if you stumble upon the way.

(FRIDGE IS UNDER ACTIVE DEVELOPMENT ALMOST REACHING v1.0)
Fridge BETA release : v0.9.3 ( UTC2022-09-24 )

Fridge - Lightweight, fast and extreeemely simple to use fetch or store mechanism.

Swiftpack.co - vexy/Fridge as Swift Package