Apollo-client: 1.0 Countdown

[Poincare]

When we started working on Apollo Client, we wrote up a design document that outlined all of the features we need for an initial production-ready version.

At this point we have working implementations of most of these features. We want to ship a "1.0" release in a reasonable timeframe to signal that people should be confident relying on Apollo Client in production, and that the APIs will remain stable for a long time.

Before we can do this, we need to identify and fix any critical problems that would block people from using it in their production GraphQL app.

Here's the list of features/fixes/etc. we think we absolutely need for the 1.0 release:

• Better documentation on all aspects of Apollo Client
• Better error handling (also involves view layers)
• Better loading state handling (also involves view layers)
• Validate the design for mutation results, pagination and fragments
  
  
  
  • For fragments, should decide whether we should use the fragment name from the document or generate a fragment name and allow referencing by variable name.
  
  
  • For mutation results, get people to use it and see what the feedback is
  
  
• Offer a way to integrate non-GraphQL data into the Apollo store (can be similar to updateQueries works on mutation results)
• Refactor QueryManager.ts to make it less complex
• Make it more convenient to pass headers, tokens, etc. in networkInterface
• Check if resetStore is a valid cache eviction strategy
• Figure out strategy for retrying queries and mutations (#439)
• Allow refetching by query/mutation name
• Look at #398 and figure out what we want to implement from it

These are the improvements @stubailo and I thought of that are currently standing between us and a 1.0 release. If you have a particular issue that is preventing you from using Apollo in production, we'd be happy to hear about it, and perhaps add it to the list.

As always, we want Apollo Client to be a community-driven effort, so if you have the need for a feature that is not in the list above, and there is a good design and pull request implemented, we can still accept it. This is just to have a complete list of "blockers" before we consider the library stable.

[saikat]

This is exciting! I just deployed our first Apollo app in production today, and overall I'm really impressed with where things are. Here's my list of issues that felt important to prioritize for a 1.0:

• Handling client-side store updates across components from the result of a mutation. Currently there are 3 ways to do this, but it's not clear to me (may just be my own lack of understanding) how to do it correctly. I think being able to have consistent state across your app is one of the biggest draws of a framework like Relay/Apollo, so I'd put this pretty high up on a 1.0 release:
  
  
  
  • Simply use refetchQuery/forceFetch in all your queries. This is, I'm assuming, the antiquated model and what we really should not use unless we have to for some reason.
  
  
  • Define dataIdFromObject and make sure to fetch id everywhere for objects that have an id. This method works remarkably well for the most part and is the approach I'm currently using almost everywhere in my app. #380 probably needs to be done for a 1.0. The main issue with this, right now, is that the component that creates the mutation needs to know all the fields from the mutation result that every other component depends on (sorry for my React-specific example here). So if ComponentA calls a mutation that modifies a TodoItem, and ComponentB which is a sibling or parent of ComponentA fetches that TodoItem, ComponentA somehow needs knowledge of the fields in TodoItem that ComponentB requires. I'm not sure if there is a good solution to this (Relay's approach is that parent components call mutations by composing in all the fragments of their children into the result, but it's not the greatest solution in the world), but it seems like an important problem to fix before 1.0.
  
  
  • Define updateQueries. This seems necessary largely for cases where your mutation is an insertion or deletion of an object in a list. However, I think this suffers from the same problem as above -- it only defines how to modify lists fetched in that component. To modify lists fetched by other components, updateQueries needs to know the names of the queries those other components use (I'm not actually sure it works if you do that, but even if it did, you essentially end up with a situation where you need to maintain a bunch of global variables and make sure to update all your updateQueries calls whenever a new query is added that relies on the updated data from that mutation).
  
  
  • Define invalidateQueries. I saw this floated as a suggestion in #448, but unless I'm mistaken, this also only will keep the current component updated and other components in the app that depend on the data will be stale.
  
  
• #451 -- I have had to rely on fragments largely to duplicate the fields in a query on the result fields in a mutation result. But when I do that right now, I'm running into this issue, so I've been relying on template string interpolation to make my 'fragments.'
• Response middleware would be cool. I've implemented it by hand in my app in a custom network interface layer (https://github.com/saikat/react-apollo-starter-kit/blob/master/src/network/response-middleware-network-interface.js), but it's a good place to put your network contract with your server (e.g. if you try to request a resource that you need authentication for, or a resource that you are not authorized to access).
• https://github.com/apollostack/react-apollo/issues/57 has been the biggest issue by far for doing dev. This is a react-apollo issue, but I think getting react-apollo to 1.0 level may be necessary to do concurrently to really reach 1.0 since so many people will be using React.

Ok hope that's helpful, and thank you all again for all the incredible work you are doing!

[HriBB]

Basically what @saikat wrote + file upload. 1.0 simply needs that.

[stubailo]

@saikat great feedback, thanks! Really appreciate it. Going to look at all the items, but for updateQueries in more detail:

updateQueries does work across all queries in the whole app, and the results are actually normalized into the store so any objects affected by the query reducer are updated in all components. I agree that this creates a somewhat undesirable situation where you need to keep track of the query names across your app.

I think this is best solved by looking at a variety if different use cases and seeing how it works out. Personally I like the idea that query names are meaningful, and you can keep track of which queries are live on the page and update them accordingly. This is better for me than keeping track of the normalized store state and dealing with it directly, but of course we can support both approaches.

@HriBB GraphQL itself doesn't have anything to say about file upload, and there are often many concerns with file upload related to tracking upload progress, etc. If Apollo Client is focused on providing a great GraphQL experience, then file upload isn't really part of that story. What kind of functionality would you be looking for?

[HriBB]

@stubailo I was trying to do a multipart/form-data upload to store a profile photo with apollo client ... did not get far :) I thought I could somehow manipulate the request with networkInterface middleware, attach FormData, then handle everything on the server before request hits the expressApollo server.

Anyway ... what is the official recommendation? Upload files via custom endpoint, then merge results into apollo store manually? Or refetch the data manually? I have seen some examples on express-graphql but haven't had the time to check it out ...

I understand that file upload has nothing to do with the GraphQL, but at least point us into the right direction :) How would you implement that?

[stubailo]

I think I would upload the file using a completely separate Express endpoint, and then when the upload is done fetch data about the file using GraphQL. Is that good enough, or is there some problem with that approach?

[HriBB]

@stubailo this is exactly how I imagined it. No problems with this approach, I just thought that it would be cool to keep everything "inside" GraphQL, if you know what I mean :)

Just wondering ... will file upload ever be a part of GraphQL, or is this just something that really does not belong in the GQL?

[stubailo]

will file upload ever be a part of GraphQL, or is this just something that really does not belong in the GQL?

I'm not sure! I don't actually see a lot of benefits in doing file upload through GraphQL, but I'm open to ideas about how it could work.

[tomsdev]

Any updates on this? Given the features/refactoring you mentioned, what would be your best-case and worst-case time estimates to reach 1.0?

[tomsdev]

Gentle ping in case you have some ETA in mind now :)

[stubailo]

Well, it sure would be convenient for us if it lined up with http://graphqlsummit.com/ 😉

I think that can be used as a rough timeline.

[geirman]

Apollo Client 0.5 New features and improvements to make GraphQL even easier

With the 0.5 release, Apollo Client is officially fully featured, stable and ready to be used in production.

To me, that means version 1.0 :-/. Regardless, congratulations for coming so far and accomplishing so much! I'm just dipping my toe, but am so happy there's an alternative to Relay.

[stubailo]

Yeah, I am pretty sure the difference between 0.5 and 1.0 won't be very big externally. It's more about making sure we go through edge cases like error handling, carefully deprecate old APIs, etc. 1.0 is about committing to API backwards compatibility until 2.0. But I agree it's mostly a cosmetic distinction.

[crubier]

Hello, any news on this ? 1.0 is still not here and I am not willing to commit to Apollo too much until 1.0 comes, as I have been burnt by incompatible changes on Apollo client before...

[thebigredgeek]

For uploads: https://github.com/HriBB/apollo-upload-network-interface/issues/5#issuecomment-288652875

[thebigredgeek]

@crubier usually upgrading is pretty simple. I've been upgrading almost non stop since 0.4, and I haven't ever encountered a breaking change that wasn't listed in the [change log[(https://github.com/apollographql/apollo-client/blob/master/CHANGELOG.md). There has almost always been enough information in the change log to modify my code within 5 or 10 minutes and get it working again. Otherwise, it takes under an hour talking to the core contribs on Slack :)

[helfer]

1.0 is out.