Under-the-hood of Apollo

This post comes from a recent talk I did on the internals of Apollo Client. See the video here. I was frustrated that I did not understand what was actually going on when I was using it so I took some time to delve into the code.

This post focuses on a single and relatively simple user-case, that is

• 100% React JS and client-side
• Simple Query component (no Mutation)
• No Subscriptions/Batching
• No complicated Caching or Memory strategy

I plan to do a follow up looking at the more advanced functionality.

This is part of my “under-the-hood of” series:

• Type systems (e.g. TypeScript)
• Source maps
• React hooks
• Web bundlers (e.g. Webpack)

Apollo organisation architecture

I thought it interesting to take an overview of the Apollo organisation on Github. The setup of the components we are interested in looks like the below image.

Key points

• Split into repositories and mono-repositories
• Total of 130 repositories
• Large number in TypeScript (all of the ones we are interested in here)
• Design principles and Roadmap included (to give community and users direction)

Observables

Observables are an important mechanism of how Apollo works, so I thought it best to do a brief reminder of what they are.

In brief:

• New async primitive (like promises and streams)
• With some powerful properties (lazy, run sequence multiple times, cancelable, operators built-in for easy data manipulation).

Example usage:

1. Create observable

subscriptionFunction = (observer) => {
  // run some code...
  observer.next("call next in sequence");
  observer.complete();
  return () =>  console.log("unsubscribe has been called")
}
observableObject = new Observable(subscriptionFunction);

An Observable is just a function which takes an Observer and returns a function

2. Subscribe to observable:

subscription = observableObject.subscribe({
  next(x) { console.log(x) }, // "call next in sequence"
  error(err) { console.log("receives terminating error of the sequence.") },
  complete() { console.log("Stream has completed successfully.") }
});
subscription.unsubscribe();

Subscribing to the observer will trigger the subscriptions function. It can be used for sync or async operations.

They work with a pub/sub model.

Define a 1-to-many relationship between objects. When the state changes for one object the dependents are notified and updated.

Now we are going to focus on the Apollo client code itself.

SHOW ME THE CODE !!

We are going to focus on what a basic “hello world” looks like for Apollo. Something which you might find online. There are 2 parts to this.

index.js (left below)

This includes our setup and configuration.

app.js (right below)

This includes the Query component, query details and rendering of the response inside another component.

Our example app

We will now break down each of the components used, including a brief statement about how they work and a screenshot to help.

Simple JS data store

An Observable is returned. On trigger runs fetch which then runs next in observed sequence with response. NOTE: fetch has to be available already.

The bridge between the Observable in HTTPLink, the cache, and our Query component. Doing processing on the data in-between (more on that in future posts).

Thin wrapper making this.context.client available to all rendered children

Gets query ready for processing on a GraphQL server

The meaty part !

High-level view of the order of events occurring.

The breakdown…

So thats it, if you notice any mistakes or have any questions please do let me know.

Personally I found it helpful to understand some of the edge-cases I would notice during development. For instance SSR doesn’t work out-the-box due to subscribe/fetch sequence of events all inside DOM mounting.

I hope you found something in this post interesting or useful.

The next step is to look at the more advanced features like Mutations, caching, batching etc. I am very excited to see what that yields.

Thanks, Craig :)