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.

[shaps80]

Just a quick update, I've been pretty busy with some foundational steps for v6. I've also been quite busy on other work, so I realise it's been pretty quiet here for a few weeks. But a LOT of async progress has been made and I'm hoping to be able to share some of that work in the near future.

That being said, it's December now and we're getting close to Christmas break and I'll be off for a few weeks on holiday.

Just wanted to give a minor update to ensure no one thinks this has suddenly been abandoned 👍

[shaps80]

Updates

---

I've completely rewritten (including tests) the low level GraphQL package to include an all-new global actor, GraphQLActor. This brings automatic thread-safety (for 99% of cases) without the developer doing anything.

This also therefore brings with it, async/await at the foundational level, as well as Swift error handling (throws) throughout, ensuring a smooth developer experience and easier to read, maintain, test and debug code.

In addition it has a new Client (thin URLSession wrapper) implementation that is built to work with the new actor and acts as a great starting point especially for people wanting to work directly with that framework, since you can write string
-based queries and get back JSON responses without using the CodeGen and Consumer level APIs if that's your preference.

This approach greatly improves testing as well since it provides a simple but effective API, great documentation and logging, as well as good error handling and feedback where appropriate.

---

Strengthening the foundation is a strong goal here, making it easier to build up the stack and ensure we still adhere to those design principles Mat outlined long ago:

• 🚀 If your project compiles, your queries work
• 🦉 Use Swift in favour of GraphQL
• 🕊 Packages shouldn't lock you in to the "framework"

To take this slightly further, I wanted to ensure the libraries feel 'at home' in Swift. An early design goal was to allow the user to 'forget' about GraphQL altogether, and I completely agree.

To achieve that goal, I've made improvements to naming, structure and API to provide a design that more closely matches a Swift developers expectations.

The goal here, to make the library even more accessible and lower the learning curve required. As well as truly removing the dep on prior GraphQL knowledge.

---

I'm excited to soon share some updates on the consumer level APIs, as I feel that for most users, that will be the entry point and so making that extremely intuitive for Swift developers, while also bringing more flexibility, type and thread safety, and improved documentation (docs, examples, demos).

The next big update for this will begin shortly on #194 if anyone is interested 👍

[shaps80]

Just an FYI, I've updated this Roadmap description above if anyone's interested.