Draft: Design principles

[stubailo]

I think we should agree on a set of principles that define why this library exists. They will help frame future decisions about the design, and make it clear how it is different from other GraphQL client libraries.

[stubailo]

@jbaxleyiii @helfer if you have time would be good to get your eyes on this!

[jbaxleyiii]

Optimistic UI for mutations

Are you thinking about direct view layer integration, or hooks / callbacks to be applied to the view layer as is spec of the view library?

A potential 8. or 7.a that I would love to see is a spec for requesting the total count of a data source with or without arguments applied. This is less of a client feature though 👍

Otherwise, I think this looks great. I'm not sure if I'm more excited about the library, or writing analytics and reporting middleware for it haha.

[stubailo]

By optimistic ui I mean being able to modify the cache temporarily and see that reflected in the UI, then roll back that change later when you get the real response from the server.

[stubailo]

As for tools, the things I'd most love to see are debugging and logging - so that you can easily track what queries are represented in your UI, and how they translate to server requests!

[mquandalle]

and pre-fetching?

[lorensr]

Not tied to UI, so you decide when to request the next page of data. So you can trigger it early, before the UI needs it.

[mquandalle]

Well I wasn’t speaking about point 7. specifically but just wanted to add “pre-fetching” as a necessary feature. Turns out that this was already listed (as 4.) and I missed it, oops.

[stubailo]

Yep, that's exactly (4)!

[martijnwalraven]

I really like these design principles, so my questions are primarily about better understanding what we are and are not building.

• Is the main reason we're not building on Relay the fact that its codebase is too complex and would contradict the principles of transparency and modularity? What are we missing out on because we're not using Relay?
• Are we building on Redux then, or is this a completely new effort? (The README says 'A simple but functional GraphQL client built on Redux for a great development experience.', but the repo tagline says 'An easy to use and understand JavaScript GraphQL client with Relay's most useful features').
• How does this library relate to the high level design for reactivity? For instance, is dependency tracking a design goal for the client?

[lorensr]

make it clear how it is different from other GraphQL client libraries.

Further help would be including in docs at launch a list of the other major libs and what the differences are.

How does this library relate to the high level design for reactivity?

It's the entire "Client data" layer, right?

For instance, is dependency tracking a design goal for the client?

Falls under "There might be optimizations that rely on specific server-side features", but might be nice addition to implementation section

1. Minimal server roundtrips to render the initial UI

Any plans for a fast-render equivalent?

[stubailo]

@martijnwalraven:

Is the main reason we're not building on Relay the fact that its codebase is too complex and would contradict the principles of transparency and modularity?

It doesn't seem to me that Relay was built from the start with these ideas in mind. There are some efforts to factor out some of the core libraries, and I'm going to be following and hopefully contributing to those with great interest. I think it will be easier to determine the tradeoffs after another week of prototyping.

What are we missing out on because we're not using Relay?

This is the hardest part to truly understand, and will also be helped by a few weeks of prototyping, testing, and hopefully talking to the Relay team in depth. I think there's a world where Relay is the most optimized approach that has all of the bells and whistles, and you use it if your app has very strict performance requirements. Then the most useful features from Relay can be brought into the Apollo client for people who don't need as much of that.

Are we building on Redux then, or is this a completely new effort? (The README says 'A simple but functional GraphQL client built on Redux for a great development experience.', but the repo tagline says 'An easy to use and understand JavaScript GraphQL client with Relay's most useful features').

Good point. I've made the tagline in the README more vague. I'm worried that the word "Redux" might immediately confuse people into thinking they have to buy into the whole Redux philosophy to use this. I suspect Redux will be a useful part of the implementation, but we'll cross that bridge when we get there.

How does this library relate to the high level design for reactivity? For instance, is dependency tracking a design goal for the client?

I think having a client that can support this stuff easily via an extension should be a primary goal. It would be built on feature (3. The ability to manually refetch data when you know it has changed).

To be fair, our understanding of the server-side design has changed quite a bit as well since that initial document, so hopefully we can make that more clear soon (we have a devshop talk and some blog posts coming out about that in the next few weeks).

@lorensr:

Further help would be including in docs at launch a list of the other major libs and what the differences are.

Great idea! As a good side-effect, this will force us to really understand those other libraries.

Any plans for a fast-render equivalent?

I think it should be easy to do the query aggregation on the server, then hydrate the store on the client. This is something we get for free from the design principle of the store being a plain object, so you can serialize it and send it around wherever you want.

[helfer]

I think these principles are exactly right. I just have one nitpick about the feature list: I assume these are not in order of importance/priority, so I would use bullet points instead of numbers. If this is indeed by order of importance, then I think we should have a discussion about that specifically.

[stubailo]

Merged it in! Please submit PRs for further comments and improvements.