Base Architecture

[nevir]

Herein lies an overview of the architecture as well as the interfaces (and more detailed algorithms) that satisfy it.

I'd suggest starting with docs/Architecture.md, which explains the broad strokes. Then, follow up with the individual interfaces; roughly in this order:

src/*Snapshot.ts which describe the shape of the various pieces of the cache.

src/Cache.ts which is the entry point into this module, to (roughly) satisfy Apollo Client 2.0's new cache API

src/operations/* for the actual work we perform against the cache.

---

Note that I haven't gotten to the following pieces of the architecture:

• Query observers.
• Apollo Client's abstraction around transactions, and optimistic transactions.

However, I'm pretty confident they can be built given all the components outlined here. Will be fast-following this PR with their architecture, as well.

[EvanBoyle]

I think that it would be helpful to reason about optimistic updates by calling out explicit scenarios:

1. User is offline for an extended period of time. App should behave as normal and network calls can be replayed once reconnected.
2. User is mostly connected, updates will succeed the vast majority of the time.

In case 1 it seems reasonable to merge state changes directly to the cache. During an extended offline session, these changes would likely pile up and replaying events could become really slow.

Case 2 (well connected) seems like fewer updates would pile up at a given point in time and replaying them each time server data comes in wouldn't be too big of an issue.

One idea for a simplified optimistic update mechanism could be to merge all optimistic updates to the cache while still maintaining a queue of state changes. If one of the updates fails, you could bust the cache pulling fresh state from the server and then replay the additional queued state changes.

[nevir]

In case 1 it seems reasonable to merge state changes directly to the cache. During an extended offline session, these changes would likely pile up and replaying events could become really slow.

Unfortunately, I don't think it's safe to merge them directly into the cache:

• When we do end up getting back online, after the update finally flushes, the server may disagree, but we still want to represent the optimistic state until all optimistic updates have flushed.

• Those requests could still fail at some point, which should invalidate that specific update, but not others. If we merge directly into the cache, we lose all ability to safely roll back.

---

I think we can flip the merging around: merge all the updates into one delta (as opposed to replaying one at a time), and just apply that merged update when the base store changes. It gets a little tricky, though, as each update can be rooted at a different node in the graph

Pulling enough server state to cover all updates may be untenable (too much data, or too many joins)

[RylanH]

Do you mean (2)?

[nevir]

Doh, yup.

[RylanH]

satisfying -> satisified?

[nevir]

We want our queries to feel like: