Skip to content

Commit

Permalink
Updated README and initial Documentation. Provided basic app samples.
Browse files Browse the repository at this point in the history
Closes #30
Closes #40
Closes #26
  • Loading branch information
vexy committed Dec 20, 2023
1 parent 0273932 commit 62fa4ad
Show file tree
Hide file tree
Showing 7 changed files with 156 additions and 167 deletions.
32 changes: 32 additions & 0 deletions Docs/Examples/Grab_example.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
import UIKit
import Fridge

//MARK: - Basic network Grab example

// define your URL endpoint
let todoEndpoint = URL(string: "https://jsonplaceholder.typicode.com/todos/")!

// conform your struct to Decodable
struct ToDo: Decodable {
var id: Int
var title: String
var completed: Bool
}

//TODO: Use other async methods that serve your needs
async {
print("---> Grabbing all TODO objects from URL endpoint using Fridge")
do {
// ** Grab with Fridge !! **
let results: [ToDo] = try await Fridge.grab🔮(from: todoEndpoint)

// do something with results....
for item in results {
print("ID:\t\(item.id)")
print("Title:\t\(item.title)")
}
} catch let fridgeError {
// handle any errors that we received
print("Grab failed. Error: \(fridgeError)")
}
}
44 changes: 44 additions & 0 deletions Docs/Examples/Push_example.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
import UIKit
import Fridge

//MARK: - Simple network Push example

// define your URL endpoint
let networkEndpoint = URL(string: "https://jsonplaceholder.typicode.com/comments/")!

// Conform your struct to Codable
struct Comment: Codable, CustomDebugStringConvertible {
let postId: Int
let id: Int
let name: String
let email: String
let body: String

var debugDescription: String {
return "[Comment] (ID:\(id)) \(name) - \(email). Body: \(body)"
}
}

//TODO: Use other async methods that serve your needs
async {
print("---> Pushing custom struct to URL endpoint using Fridge...")
do {
let newComment = Comment(
postId: 12,
id: 100,
name: "New comment",
email: "[email protected]",
body: "Body of the new comment"
)

// ** Push data using Fridge !! **
let response: Comment = try await Fridge.push📡(newComment, to: networkEndpoint)

// handle response...
print("New comment successfuly pushed")
print("Returned response: ", response)
} catch let fridgeError {
// handle any errors that we received
print("Grab failed. Error: \(fridgeError)")
}
}
File renamed without changes.
7 changes: 6 additions & 1 deletion Guides/Usage.md → Docs/Usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,12 @@ For deeper information, you can check `in-code` documentation.

---

## Network fetching
## Network fetching
|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_)|

With Fridge, network fetching is performed in just 3 steps:
1. Conform your desired `struct` to `Decodable`
2. Define `URL` endpoint where your model resides
Expand Down
54 changes: 0 additions & 54 deletions Guides/Examples/Fridge basics.playground/Contents.swift

This file was deleted.

This file was deleted.

182 changes: 74 additions & 108 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,145 +3,110 @@
</h1>

<p align="center">
<b>Fridge</b> - extremely simple <code>async/await</code> fetch-and-store implementation you'll ever see !<br>
Let your fancy <code>struct</code>(s) raise and shine again, allowing you to focus on 💬 🥊🤖⭐️🗝 <i>stuff</i>.<br><br>
</p>
<br><br>

<table style="width:100%">
<!-- <tr>
<th># HEADERS HIDDEN #</th>
</tr> -->
<tr style="outline: thin; vertical-align: middle">
<td>
<a href=https://github.com/vexy/Fridge/actions/workflows/release_workflow.yml">
<img alt="Release build" src="https://github.com/vexy/Fridge/actions/workflows/release_workflow.yml/badge.svg">
</a>
</td>
<td>
<a href="https://github.com/vexy/Fridge/releases">
<img alt="GitHub release (latest by date)" src="https://img.shields.io/github/v/release/vexy/Fridge?color=green&display_name=release&label=Latest%20release">
</a>
</td>
<td>
<img alt="Platforms" src="https://img.shields.io/badge/Platform-iOS%2C%20macOS%2C%20tvOS%2C%20watchOS-blue"></td>
<td>
<a href="https://github.com/vexy/Fridge/blob/master/LICENSE"><img alt="License" src="https://img.shields.io/github/license/vexy/Fridge"></a>
</td>
</tr>
</table>
<b>Fridge</b> is <code>Swift</code> based freezing device.<br>
It helps you <b>fetch-n-store</b> data without major hassle.<br><br>
<i>Lightweight, Async/Await friendly, Zero dependency, <code>Foundation</code> based.</i>

<div align="center", style="border: 0.15px dashed yellow; padding: 1px">
<a href="https://github.com/vexy/Fridge/releases">
<img alt="GitHub release (latest by date)" src="https://img.shields.io/github/v/release/vexy/Fridge?color=green&display_name=release&label=Latest%20release">
</a>
<img src="https://img.shields.io/github/languages/code-size/vexy/fridge?color=g">
<a href="https://github.com/vexy/Fridge/blob/master/LICENSE">
<img alt="License" src="https://img.shields.io/github/license/vexy/Fridge">
</a>
</div>
</p>

---

<!--
BELOW IS THE TABLE OF RELEASE AND TEST PLANS. FIX BEFORE PUBLISHING
<table style="width:100%">
<tr style="outline: thin; vertical-align: middle">
<td>
<a href="https://github.com/vexy/Fridge/actions/workflows/tests_workflow.yml">
<img alt="Tets build" src="https://github.com/vexy/Fridge/actions/workflows/tests_workflow.yml/badge.svg">
</a>
</td>
<td>
<a href="https://github.com/vexy/Fridge/actions/workflows/macos_workflow.yml">
<img alt="MacOS build" src="https://github.com/vexy/Fridge/actions/workflows/macos_workflow.yml/badge.svg">
</a>
<td>
<td>
<a href="https://github.com/vexy/Fridge/actions/workflows/tvos_tests.yml">
<img alt="TvOS build" src="https://github.com/vexy/Fridge/actions/workflows/tvos_tests.yml/badge.svg">
</a>
<td>
<td>
<a href="https://github.com/vexy/Fridge/actions/workflows/watchos_tests.yml">
<img alt="TvOS build" src="https://github.com/vexy/Fridge/actions/workflows/watchos_tests.yml/badge.svg">
</a>
<td>
</tr>
</table>
---
-->

<br>
<p align="center">
<h3>Supported platforms</h3>
<img alt="Platforms" src="https://img.shields.io/badge/Platform-iOS%2C%20macOS%2C%20tvOS%2C%20watchOS-blue">
<a href="https://github.com/vexy/Fridge/issues">
<img alt="Issues" src="https://img.shields.io/github/issues/vexy/fridge">
</a>
<h3>Tests</h3>
<a href=https://github.com/vexy/Fridge/actions/workflows/release_workflow.yml">
<img alt="Release build" src="https://github.com/vexy/Fridge/actions/workflows/release_workflow.yml/badge.svg">
</a>
<a href="https://github.com/vexy/Fridge/actions/workflows/tests_workflow.yml">
<img alt="Tets build" src="https://github.com/vexy/Fridge/actions/workflows/tests_workflow.yml/badge.svg">
</a>
<a href="https://github.com/vexy/Fridge/issues">
<img alt="Issues" src="https://img.shields.io/github/issues/vexy/fridge">
</a>
<img src="https://img.shields.io/github/languages/code-size/vexy/fridge?color=g">
</p>

# 💠 Library interface
`Fridge` is a freezing device ❄️. It **has** to keep things cool enough, exposing just icy interface.
## 💠 Library description
`Fridge` is a freezing device ❄️ so 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:
Fridge is designed to _reduce the pain with most common software operations_ such as **[fetching](#networking-🕸)** and **[storing](#persistant-local-storage-💾)** data. Or something like this:
- 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! 🤷🏻‍♂️
- storing _the stuff_ somewhere on disk
- doing boring _error checking_ again
- invoking more than 1 dependency for this (not using `Fridge`)
- and yeah... even cursing old **closures**.
- (not)doing tests

Checkout [documentation](Guides/Usage.md) for more information.
Fridge is so `async/await` friendly and designed with simplicity and flexibility in hand. With Fridge, you can even _say goodbye to closures and CoreData_ if you want! 🤷🏻‍♂️

### 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|
Checkout [documentation](Docs/Usage.md) for more information.

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](Guides/Usage.md) for more information.
> _Talking is cheap. Show me the code._ - Linus Torvalds
# Quick code example
## Networking 🕸
```Swift
// 1. Conform your fancy struct to Decodable
struct GHRepo: Decodable {
var name: String
var repositoryURL: URL
// ... other fields
// define your endpoint
let endpoint = URL("https://github.com/vexy/")!

// conform your fancy struct to Decodable
struct GitHubRepoObject: Decodable {
var name: String
var repositoryURL: URL

// ... some other fields
}

// use Fridge to grab🔮 data from the network endpoint
do {
// 2. Await for grab🔮 method...
let myRepo: GHRepo = try await Fridge.grab🔮(from: URL("https://github.com/vexy/")!)
let myRepo: GitHubRepoObject = try await Fridge.grab🔮(from: endpoint)

// do something with your object
print(myRepo)
print(myRepo.name)
} catch let err {
print("Naaah.. Something bad happened: \(err)")
}
```
Checkout more [_documentation on networking_](Docs/Usage.md#network-fetching) or start with basic [code **examples**](Docs/Examples/).


## Persistant (local) storage 💾

// 3. Then, at your will, use myRepo as any other Foundation object
print(myRepo)
print(myRepo.name)
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.


// ... something ...
```Swift
// conform your fancy struct to Decodable
struct GitHubRepoObject: Decodable {
var name: String
var repositoryURL: URL
}

// 4. Later on...
// freeze it to local storage in just on line
do {
try Fridge.freeze🧊(myRepo, id: "myIdentifier")
} catch let e {
print("Whoops... Here: \(e)")
print("Whoops... Can't freeze because: \(e)")
}
```

> _Talking is cheap. Show me the code._ - Linus Torvalds
Checkout [documentation](Docs/Usage.md) for more information.

# Real world use cases
Here is some **real world** usage of `Fridge`:
- [**Clmn** - _Beautiful macOS app that operates with tasks in columns_](https://github.com/igr/Clmn)
- [Playground examples of Fridge practical usage](/Guides/Examples/Fridge%20basics.playground/Contents.swift)
- [Clmn](https://github.com/igr/Clmn) - Beautiful macOS app that operates with tasks in columns
- [Sample code](/Docs/Examples) - with Fridge in practical usage

# Installation instructions
## Installation instructions
Using `Swift Package Manager` is by far the sexiest way to install `Fridge`.

```Swift
Expand All @@ -166,7 +131,7 @@ url: "https://github.com/vexy/Fridge.git"
branch: "main"
```

## Minimum versions required
### Minimum versions required
For `Fridge` to work in full capacity, following Swift & iOS configuration is _recommended_:
- Xcode `13.1+`
- Swift `5.5`
Expand All @@ -190,13 +155,14 @@ That may be helpfull for `Xcode 12.x`, assuming `Swift 5.x` is installed.
Checkout official [Swift.org](https://www.swift.org/) website, for supporting earlier than minimums and other info.

## External dependencies
Fridge uses [BSONCoder v0.9](https://github.com/vexy/bsoncoder) - Copyright by [Vexy](https://github.com/vexy).
Check original library licencing information under licencing section in README file.

Since `v1.0` Fridge **does not** use anything other than Foundation provided `JSONEncoder`.
Up to `v0.9.2` Fridge used [BSONCoder v0.9](https://github.com/vexy/bsoncoder) as main encoding device.

# Documentation
> _RTFM isn't a joke..._ 🥴
In the **[Docs](Guides/Usage.md)** you'll quickly figure out how to:
In the **[Docs](Docs/Usage.md)** you'll quickly figure out how to:
- *easily fetch object* from the network,
- *persistently store* your objects,
- *load them back* into your app,
Expand Down

0 comments on commit 62fa4ad

Please sign in to comment.