Autumn '24 🍂 Status Update

[jasonkuhrt]

It is October now and I've been actively working on Graffle without an "official" update since summer so here's my most recent thoughts and plans.

Summer passed with a lot of progress on documentation and the extension system. Some highlights were:

1. A rich and growing set of examples that double as tests and documentation.
2. Feedback from the community. This means lot to me, providing motivation. Thank you! <3
   • Very early v8 feedback #1152
   • Spring 🌼 Status Update #922 (comment)
3. Extensions can extend chaining apis
4. Clarity around how to make Scalars work as extensions

Some setbacks were:

1. Twoslash Vitest eventually no longer being able to compile the website so I had to pull that functionality, for now.
2. Work generally taking me longer than I think it will :)

A few months ago I thought I was going to be able to release Graffle come September but I've since shifted my view on that. Here are my plans going forward:

1. Address all user issues as they come in, paper cuts and confusion or just bugs.

2. I want to keep the core very lean so that it can be a minimal GraphQL client solution suitable for bundling into a client. Achieving this means having a powerful extension system.

3. In the spirit of the above, make the runtime schema optional and small.

   Graffle has achieved a few features by keeping a "runtime schema" but since the beginning I've been concerned about this due to the unbounded size of GraphQL schemas. For example, I want to have an auto-generated GraphQL client for the GitHub API npm add @graffle/client-github but it doesn't strike me as realistic to pitch "and keep a runtime representation of the whole GitHub GraphQL schema in your bundle too".

   Here's where the runtime schema is used.

   1. Supporting automatic encoding and decoding of runtime scalars.
   2. Supporting the ability to have schema errors separated from other results, including having them thrown automatically (or imagine turned into the Left in an Either type etc.).

   Currently those features are built into core which means that users have no option about their use. I want to change that. Both custom scalars and schema errors should become extensions. This is tricky because there is a build time generation step that those features depend on so I must now include the ability to extend the generator. I am actually excited about that though and think it's a great direction.

   Once those features are extensions, it means users will only pay for the bundle cost of a runtime schema if they benefit from it. Furthermore I also am taking steps to reduce the runtime schema from a full representation to instead minimal subsets that only provide just enough information for the feature. I have already for example finished the generator for a custom scalars index that contains just paths to custom scalar locations (see example here).

4. Graffle and GraphQL (raw) interface symmetry.

   For a while I was considering raw as an escape hatch that would not participate in features like custom scalars and schema errors. I have changed my mind about this as I've realized it's not a stretch to achieve symmetry. I also think its pretty confusing to keep track of the difference feature support between them. It's a much simpler story to just say for example that custom scalars are decoded and encoded with every request however you make it, full stop.

   Achieving this means doing document manipulation. If you send a raw string GraphQL document there will be some parse/print overhead but these will be opt-in, minimal overhead in most cases I expect (perhaps massive documents start to see more than single digit milliseconds cost?), and not present if you use other interfaces like sending a GraphQL document instances with raw or the Graffle interface.

5. CLI into own Package

   I haven't fully figured this one out but I would like to extract the generator and CLI of into a new package that supports various points here about keeping a lean core. While the CLI should anyways be dropped via tree-shaking I think it still makes sense to keep graffle package apart from say graffle-cli. I may go the way of Prisma here having graffle be a CLI and @graffle/client be the core package. I'm curious to hear feedback about package naming. I still need to think this over more myself.

6. New GitHub Organization

   Finally a more meta thing. I've been offered some financial support to work on Graffle but part of meeting the criteria for that includes moving Graffle to an org that encourages more community involvement. To that end, I have decided to move this repo to https://github.com/graffle-js. Over time additional repos will be made for example for each first-party extension.

---

Alright, those are my major thoughts for now. So to recap:

1. Ability to extend generator
2. Schema Errors as extension
3. Custom scalars as extension
4. Separate packages for extensions, cli
5. Slim Core
6. Feature symmetry between all interfaces (GraphQL (raw), Graffle)
7. New org for this repo

Thanks for your attention and let me know what you think! Cheers

[jasonkuhrt]

Oh, and make raw great: #1164

[jasonkuhrt]

It's been busy couple of weeks, made a lot of progress. Getting back to website work this week.

[jasonkuhrt]

Work has been going well. I sent into a minor slump rewriting to/from mappers at type/term levels in order to bring extension and request pipeline feature parity between gql and Document Builder. With that work done I'm not shifting to bundle size which is a great motivator for now tackling a bunch of lingering core issues.

All of that is in my currently pinned issues if you're curious.

• Reduce base bundle size #1216
• Reduce bundle size with graphql.web #1223
• Overhaul Core #1236