Apollo Client local state

[hwillson]

In a nutshell, this PR migrates the local state handling capabilities provided by apollo-link-state, into the Apollo Client core. @client directive handling is fully managed by Apollo Client (through the QueryManager), without requiring a separate Apollo Link.

Please note: Apollo Client local state functionality is in an alpha state. We're still considering changes, which might affect the public API.

While opinionated, these changes are being considered to help address several outstanding apollo-link-state issues that are difficult to address in a link chain, and open the door to future Apollo Client changes that integrate local state handling more closely with the Apollo Cache.

The implementation outlined in this PR closely mirrors existing apollo-link-state functionality, with a few changes / additions to make handling local state with Apollo Client more flexible and easy to use.

Key Changes

• It is no longer necessary to add apollo-link-state to your link chain. Apollo Client includes all local state functionality out of the box.

• The idea of initializing your local cache with apollo-link-state's fixed defaults option has been replaced with a new initializer function approach. Initializers are simple functions, that can be run during ApolloClient instantiation, or via the ApolloClient.runInitializers function. These functions are mapped against the name of the field you want to update in the cache, and the result of running the function is stored in the cache against that field. Initializers can be as flexible as you need them to be, and can either write the returned result directly to the cache, or be configured to skip writing to the cache, letting you handle that manually inside the initializer function yourself. Each initializer function is called with access to the ApolloClient instance, so the full AC API is available.

• Initializers do not check to see if they'll overwrite existing data when run. For now we're avoiding the extra cache hit of having initializers check to see if data already exists for a field, before overwriting it. This functionality can be overwritten by manually checking and updating the cache yourself in an initializer function.

• Initializers are only run once (to help prevent overwriting data accidentally).

• Local resolvers can be set through the ApolloClient resolvers constructor param, or by calling the ApolloClient.addResolvers function.

• A local schema can be defined by passing it into the ApolloClient constructor via the typeDefs parameter.

• Mixing remote and local fields together in queries / selection sets (aka virtual fields) is still supported, along with some additional features. @client ... @export(as: "someVar") can now be used to pass the result of a locally resolved query in as a variable for a remote query, all in the same request. For example:

query authorPosts($authorId: Int!) {                                          
  currentAuthor @client {                                                     
    id @export(as: "authorId")                                                
    firstName                                                                 
  }                                                                           
                                                                              
  author(id: $authorId) {                                                     
    id                                                                        
    firstName                                                                 
    posts {                                                                   
      title                                                                   
      votes                                                                   
    }                                                                         
  } 
}

• Subscriptions now recognize the @client directive, meaning locally resolved data can be combined with incoming subscription data.

• Full SSR support.

• Numerous bug fixes and changes made to address outstanding apollo-link-state issues (issues labelled as ac-local-state-ready are fixed by these changes).

• And more! 🙂

This PR is still a work in progress (and is not ready for review), but we're pushing hard to get it wrapped up soon.

TODO:

Documentation. This PR is already getting pretty large, so I'll submit the updated local state docs in a separate PR.

[hwillson]

Just a quick note about the bundle size increase here - it's temporary, and will be pruned down shortly.

[alidcast]

@hwillson fyi - I'm trying this locally in react-native and the data turns undefined unless I initialize it myself before querying, i.e. writeData({ data: { isLoggedIn: true } }) (which im totally fine with, but figured I'd let you know)

the tutorial online did not have setup intructions but from looking at PR, pretty sure im passing the options correctly so not sure why the initializers aren't working

new ApolloClient({
    ...
    typeDefs: gql`
     extend type Query {
      isLoggedIn: Boolean!
    }
   `,
    initializers: {
      isLoggedIn: () => false
   }
  })
}

also, will initializers support async functions? It'll be necessary in order for the isLoggedIn example to work with react-native since theAsyncStorage methods return promises

[alidcast]

another issue Im seeing is that for the first query, the data is not available and returns an empty object first and then the result, i.e. {} then {isLoggedIn: true} which causes the need for unnecessary loading/conditionals so the wrong view is not rendered (but this could perhaps be related to above initializer configuration not working)

(if you're not seeking early testing right now, apologies and ignore these comments!)

[hwillson]

@alidcastano We're definitely seeking feedback, so thanks for this!

Initializers called during ApolloClient instantiation are run synchronously, so the cache should be prepped before your first call against it. Your code sample looks right, and you shouldn't have to call a writeData yourself. Can you confirm which exact version of apollo-client@alpha you have installed?

Regarding initializers supporting async, they do currently, but not via the ApolloClient constructor. Initializers called through the constructor run synchronously, so we can make sure the cache is prepped in the expected state before a query is fired against it. ApolloClient's runInitializers method supports async though - e.g.:

const client = new ApolloClient({ ... });
...
client.runInitializers(async () => {
  await someFunction();
  ...
});

[alidcast]

hmm for some reason the intializers weren't working before but now they are 👍

in regards to the async functions, passing a function to runInitializers didn't work, and I couldn't find support for it in the code or tests from this PR

but I was able to get it working using the following code

// schema.ts
...
const initializers = (ctx) => ({
  isLoggedIn: () => !!(auth.getToken(ctx && ctx.req))
})

// index.ts
function createClient(initialState = null, ctx = null) {
    ...
  const client = new ApolloClient({ ...., typeDefs })

   // note: only run initializers / return promise if there's no initial state
  // so that we don't have to wait when rehydrating client 
   if (!initialState) {
    return client
      .runInitializers(initializers(ctx))
      .then(() => client)
  }
  return client 
}

(^^ I'm guessing we don't need to pass the initializes as a constructor option if we're running them ourselves)

my project is a react native app and a server-rendered web app (using react-native-web), so i can confirm in works on both environments!

[chaffeqa]

FYI we just cut over to try this out, seems to be working fine!

Using SSR and web client-side (for PWA support)

[hwillson]

Quick note - this PR has been replaced by #4338. We'll continue the discussion there. Thanks!