Detailed information about Teller to add to some docs.

[levibostian]

The README is good as an overview. However, to truly understand Teller and how it was designed in it's detail, there needs to have some questions answered.

[levibostian]

When you have an OnlineRepository that you call observe() on for the first time and that first fetch fails, it is up to you to do one of the following to try again: it will continue to listen for events, forever.

You can change the requirements, refresh unlimited number of times and have them each succeed or fail, add more observers, etc. When you call observe(), you will only stop receiving events when the instance of OnlineRepository is disposed.

[levibostian]

The maxAgeOfData property in OnlineRepository is only checked each time that the cached data is changed in the app. This is done in purpose. Let's explain with an example.

Let's say that your OnlineRepository subclass has a maxAgeOfData of 5 minutes. If you decide to call observe() on this subclass when the cached data is 4 minutes and 59 seconds old and then you wait 2 seconds, Teller will not fetch the fresh data for you at 5 minutes and 1 second. When you call observe() and the data at that time was 4 minutes and 59 seconds, at that moment in time the data was under 5 minutes old so Teller did not update your data for you at that time.

You must call refresh() yourself if you want to refresh the content at 5 minutes and 1 second. Give your user a UI that allows them to refresh the content. You call refresh() and when refresh() is complete, you will get a result back telling you if the refresh was successful or not and your Observable you received when you called observe() will be notified of any fresh data changes made in the refresh call.

We want to give the power of the data refresh to the user.

[levibostian]

Let's say that you have a subclass of OnlineRepository called FriendRepository that contains a list of friends for a given user.

In your app you have 2 lists in the same UI. One for you and one for your company account. You want to show 2 lists in the same screen.

You ask me, "How do I use FriendRepository to populate 2 separate lists in my 1 screen?!"

I respond, "Create 2 instances of FriendRepository. Call observe() on both of them with 2 separate GetDataRequirements instances. You can create unlimited instances of FriendRepository and they all work independent of each other to Teller.

---

You now ask me, "What if I want to have multiple observers on 1 instance of FriendRepository?"

I respond, "You can do that. You can add as many observers to any instance of a OnlineRepository and they will all be notified when the state of the data changes."

[levibostian]

Merging this issue in here.

With Teller in the wild, it needs to work with Realm, Core Data, UserDefaults, Moya, Alamofire, etc. Popular frameworks, architectures that many people use.

Having examples of each of them to help people adopt best practices is the best thing to do I believe.

[levibostian]

Add best practice:

Only create a new OnlineDataSource for each data type in your app. If you have multiple API endpoints that return the same data type and that fetched data is saved and observed in the same way, then consolidate that logic into 1 OnlineDataSource. Use the requirements object to differentiate what fetch call to perform.

[levibostian]

Add as advanced functionality:

OnlineRepository is designed to work with only 1 data type at a time. This helps to encapsulate functionality of your app. However, you can observe/fetch 2+ different sets of data as long as it's the same data type.

Example: You can have 2 repository that can be used to fetch/observe your friends or friend requests of a user. As long as the data type, [FriendModel] as an example, is the same.

[levibostian]

Explain how to do paging with Teller and the OnlineRepository.

• How paging "just works".
• Setup data source to handle loading, fetching, saving pages of data.
• Using a paging delegate for TableView to know how to load next chunk of data.