Project Roadmap

[shaps80]

This post is to provide communication about the direction of this project and the intended roadmap, as well as its current high-level progress.

UPDATE

After several months of exploration and the development of a proof of concept, we have landed on a final design for v6 – and while its a radical shift from the current design, @maticzav and I agree its a stronger direction that will bring this library forward in every way.

I'll leave the sections below as a reference to the key issues we're attempting to solve and the associated design goals. However please check Discussion and Pull Requests for more details.

In addition I'll soon be starting a new v6 branch for anyone who wants early access to try things out. It will likely be incomplete for some time but it will give everyone an early view which may help in planning your updates in the future.

Note, while we expect everyone will want to upgrade to v6 once it's released, the design is so different that we will not have any planned migrations in place unfortunately. However we _will include documentation and examples to guide your update process.

However you can continue to use v5 if required and the update to v6 is designed to MASSIVELY simplify your GraphQL usage. So, we expect most users will welcome the change regardless and we can't wait to get your feedback and hear about your experience using SwiftGraphQL.

I will update the v6 Project board next week to help us track progress 👍

Thank, @shaps80 and @maticzav

---

Key Areas

I'll break this down into multiple sections since there's a lot to cover:

Developer experience

The current state of the union isn't great in this regard IMHO. It's not terrible but it could be far more improved. This helps with existing users, but also enables us to reach a wider audience when the barrier to entry is lowered.

• Documentation is strong, but header docs lack in examples and some external documentation it outdated
• Platform support is a little confusing atm, requiring additional unnecessary effort on the part of the developer in some situations (e.g. tvOS vs iOS support is not aligned)
• The consumer API itself is a little cumbersome at best and occasionally unclear IMO
• Dependencies are inevitable however we currently have several that are adding minimal value or were included purely as a necessity of outdated constraints
• Error reporting is lacklustre compared to the information available via GraphQL. This may be a result, in part, of the usage of Combine – however we can greatly improve this by providing more verbose, helpful output that would enable a user to diagnose issues more easily, as well as providing a useful tool for our users to copy/paste this output into a GitHub issue, improving our own ability to support these users.

Concurrency

The use of Combine has enabled the project to provide asynchronous contexts to our users and ensure we can support the wide set of features available to us via GraphQL. However it's cumbersome to use (compared to alternatives) and vastly more difficult to maintain. It also limits who can contribute because it requires in-depth knowledge on another framework that's non-trivial to become deeply familiar with.

• The reactive approach will be replaced with a modern Swift Concurrency approach
• As a result, Swift error handling will also be introduced more heavily
• Async/await simplifies user-code, improves approachability and enables a wider variety of contributors
• Other modern concurrency features will also make it easier for us to introduce thread safety across the stack

Code Generation

This is one of my favourite pieces of the library because @maticzav has done an incredible job at aligning the implementation alongside the ethos he well-defined. This is important compared to competitor projects because SwiftGraphQL just does the heavy-lifting while not locking you into specific caching, networking or model implementations. Additionally, it generates "sane" types that are easy to work with, without requiring needless name spacing and additional complexity.

However, there are also some current pitfalls.

• Additional Scalar types could be added by default (e.g. Int8, etc)
• Performance is problematic at times, large schemas can take several minutes to generate. This is particularly problematic when a schema is in-development and the user needs to regenerate more regularly. There are also CI implications here.
• In light of other points made above, we also need to update this to generate newer implementations
• Currently codegen is done via a command line tool that's distributed via Homebrew. I don't feel we should remove this, however I think other options could also be explored, including setup through Xcode and the package itself (perhaps as a Plugin) – this could simplify some user setups and potentially improve some CI workflows as well.

Summary

The above areas will be the primary focus for the v6 release, however its still very early stage so new ideas are still welcome, enabling the core-maintainers to find appropriate solutions to key areas.

---

Please note we will be locking comments on this post since it's intended purely as a way to provide open communication and updates on the v6 roadmap and its progress.