feat: Prefetch

[dickermoshe]

TBD

[dickermoshe]

@simolus3 Still needs docs and tests, but otherwise is complete.
When I have time I'll write up a much clearer explanation of what going on.
Sometime tomorrow

[dickermoshe]

🚧WIP🚧

This is how prefetching will work under the hood

Step 1 - The Callback

The user decides what he would like prefetch by using an optional call back in the withReferences method.

withReferences((o)=> o(prefetchUsers: true)).get()

Running the o function, will return a new function.
What does this function do? What does it return?

Well, the return value from o is itself an async function.

o(prefetchUsers: true) // Future<Prefetches> Function()
await o(prefetchUsers: true)() // Prefetches

Calling it will return a Prefetches object.

Step 2 - Prefetches

Well, what is a prefetches?
Relax, I'm getting to it.
Each table has a prefetches object associated with it. (yes, even more code 😟)
This holds the prefetched data. So running await o(prefetchUsers: true)() will return a class GroupsPrefetches which holds all the users for ALL the group.

Step 3 - OK, When are we running this?

Well, we don't run await o(prefetchUsers: true)() just yet. When we run withReferences((o)=> o(prefetchUsers: true)), we don't get the prefetches yet.

1. The race conditions could be even worse
2. withReferences would need to be async.

So when do we run them?
We run them when we actually do the get()

So calling withReferences(...) saves the entire callback ((o)=>o(prefetchUsers: true)) for later. This is stored on another field of the model.

Step 4 - OK, I want my references now

Sure, when you finally run get(), we will run await o(prefetchUsers: true)() we will get the prefetches for this class.
We will then insert this prefetches object into every <TableName>WithReferences object.

So when you finally run

final (group,refs)  = await groups.withReferences((o)=> o(prefetchUsers: true)).getSingle()
final users = await refs.users.get();

The refs object will insert the appropriate users from the prefetches into the cache of the newly created table manager (remember users is a table manager).
Running .get() or .watch will return from this cache on refs.users.get(), instead of making a query.

If you don't understand this, it's ok. It will make sense once you see the code (I hope)