Apollo Client integrated local state handling

[hwillson]

⚠️ This PR replaces #4155. PR 4155 included a lot of different ideas and POC work, much of which is no longer needed. Now that we're close to finalizing the local state API, this PR includes a clean subset of PR 4155.

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.

[JoviDeCroock]

Does this imply that opting out of apollo-link-state requires use of a module build and a bundler who's tree-shaking/DCE is on point?
Just trying to put this out there, with all the bundle size effort being done. Since the esm bundle PR is still open

[hwillson]

@JoviDeCroock If you can use ApolloClient in your project, then you can use the new local state handling capabilities. You don't have to worry about the module format, tree-shaking, dead code elimination, etc. if you don't want to. The bundle size reduction work that's happening in other PR's is super important, and will benefit Apollo Client across the board, but it's not required to use AC's integrated local state handling.

[chaffeqa]

Correct, and if it matters, I think this is wise. It's really hard to innovate and move quickly when you have dependent code and plugins outside of the main source.

If it helps, I believe that as the tech develops, you will be able to see the proper way to separate and package better.

[hwillson]

I'm totally open to changing the @client(always: true) naming, if people don't think it makes sense. I originally had @client(force: true) for example, but thought it wasn't super clear about the fact that adding this variable means we're telling the associated field resolver to always run.

[benjamn]

Using always: true crossed my mind too, and I like it! I think it’s a little clearer that you should never pass always: false (because that’s clearly the default) whereas force: false might conceivably trigger some non-default behavior.

[mbrowne]

Thanks for all the great work on this! This feedback might be premature, but in case it influences the API design in any way, I think an important use case will be building additional abstractions on top of local state. For example, here's an idea I have for setting up mutations without as much boilerplate code:

export const actions = createUpdaters(client, {
    counter: {
        increment: ({ count }) => ({
            count: ++count
        }),
        decrement: ({ count }) => ({
            count: --count
        })
    },
    currentUser: {
        changeName: (state, newName: string) => ({
            name: newName
        })
    }
})

The initial state that goes along with this example looks like this:

{
    // counter doesn't need to be an object of course, since it only has one property;
    // just making it an object for the sake of the example
    counter: {
        count: 0
    },
    currentUser: {
        name: 'Guest'
    }
}

createUpdaters() would turn these into updater functions that call a mutation behind the scenes. (A nice thing about mutations rather than writing to the cache directly is that they provide a possible opportunity to log every local state change, meaning something like Redux's time traveling debugging tool would be possible.)

I put together a quick POC here for anyone who's interested:
https://github.com/mbrowne/apollo-state-actions/tree/master/demo/src

One issue I ran into is that there seems to be no way to get a full object from the cache without knowing specifically which fields to request in advance. So for now I hacked it to access the private cache.data property directly. I'm not asking for a solution here, just wanted to mention it, since a non-hacky way to do this would be handy for creating libraries like this.

[pashazz]

Shouldn't there be a some kind of context interface that provides cache, getCacheKey as per documentation?

[fpaboim]

I feel that local queries are rarely computationally expensive and that most of the reason to use caching is because of the network latency/bandwidth issues, as such wouldn't it make sense to default to @client (always: false)? Or to be able to at least set it as default behavior if I so choose would be great. I feel caching local data is a great potential source for bug complaints in the future as users from other local state management libraries won't be expecting their local state to be cached and potentially read from a stale state. TBH, I find it hard to find a use case where you're running a long winding local query where caching would be a good solution, probably would be better to use workers and update your local state or something.

[mbrowne]

@fpaboim What about when you call cache.writeData() (or writeQuery or writeFragment)? Those methods write directly to the cache of course, and the next time you query the same fields I would expect it to return what you explicitly wrote to the cache rather than calling the resolver again.

[fpaboim]

True, and those should be most use cases I guess... on the other side besides localStorage the only other thing I could think of is accessing some other state, like someone using redux/mobx/context for local state?