Winter '25 ☃️ Status Update

[jasonkuhrt]

Here is my seasonal update on Graffle, this time the Winter '25 edition ☃️. The previous on was on October 3.

Autumn Retrospective

The Good

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

✅ Albeit there haven't been many, but I've kept on top of user bugs with only a few recent ones being open longer than normal due to a long living PR (more on that later).

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.

✅ I made a lot of progress towards this, getting the bundle size down to 17kb.

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

✅ Achieved this!

Graffle and GraphQL (raw) interface symmetry.

✅ Achieved this!

New GitHub Organization

✅ Did achieve this!

The Bad

CLI into own Package

❌ Did not achieve this yet

The Ugly

• I hit hard some TypeScript issues with regards to type instantiation depth limits. I eventually got around these but it took time and effort and I still don't feel confident I won't hit the problem again but I do feel more capable of tackling it again if I have than than I did back then.
  • https://bsky.app/profile/kuhrt.me/post/3lbwzspxxkc25
  • https://github.com/jasonkuhrt/experiment-ts-chain

Conclusion

I am happy that I was able to do what I said I would, for the most part. I also started work at The Guild in December 🎉, ending my three months of full-time work on Graffle. Certainly bittersweet from the point of view of the project haha.

Now The Winter Status Update! ☃️

First let's address the 🐘 in the room regarding reduction in velocity:

Work had definitely slowed since starting my new job full time in December. Such is life! It technically would be possible for me to cram 15-20+ hours a week on graffle but at what personal cost? Finding a balance is paramount for my mental health and its simply not possible for me right now to maintain a full time job, raise two children, take care of myself, my partner, and then apparently work another part-time job called Graffle. Graffle is a joy for me to develop but I won't tolerate it becoming a source of anxiety in my life. This is my art project, a labour of love, and that care I believe is also what makes it special and interesting ultimately. If ever I could financially sustain myself with open source, I would shift my position here a bit, but, so long as love is the only driver, then I must make sure this project fits into my life in a way that demonstrates love toward myself too :) - otherwise slow progress will turn into no progress.

The rabbit hole

For the past 1-2 months I've been slowly progressing in a rabbit hole that has seen me rewrite much of the Graffle data core. It has not been totally crazy though, just crazily executed. The insights I've had are about the static data core of Graffle which all its type safe chaining, extensions, transports etc. are powered by. I'm well over half way on that PR now. It must be merged before anything else happens. The result of that work leads towards a central data structure called "context" that has a set of "reducers" that operate over it at value level (runtime) AND type level. For example adding custom scalars, or transports, or extensions, or various configuration states like if an envelop should be returned by request methods. The core of Graffle becomes something even more fundamental than the client, a data structure. The client is simplified to just being a thin wrapper of methods that run these reducers. I'm excited about the changes I am making, and being excited keeps me motivated to work on Graffle :)

Road Map

I want to focus in on a stable release. It is clear to me that I will not be realizing all my ideas before some ideal release and instead need to make a cut off point with what can be stable, and then push the rest into future releases. The good news is that I'm not too far I think from a stable core and the extension system helps me defer not perfectly resolved features. Here's how I see the path ahead:

• Finish the "rabbit hole"
• Resolve open design issues of anyware:
  • Review the ergonomics of interceptors and modular transports.
  • Large relative footprint on bundle size, can we make it smaller somehow?
  • Review the input/output data types of various steps in the anyware pipeline, does it all make sense?
• Allow extensions to declare dependencies on other extensions
• Finish reference docs (JSDoc)
• Finish guide docs (website)
• Switch to a monorepo, split CLI out, all extensions, and other packages like anyware

Release Strategy

In the end, I hope to release graffle@8 such that it by default is a near drop-in replacement for graphql-request@7, just with a simpler more flexible API (e.g. switch envelope on/off, custom scalars, etc.).

I intend to keep all the extensions, and the extension system, in a pre-major release state meaning technically unstable. However the @graffle/document-builder extension will be quite mature and likely what I work on immediately next to progress to its 1.x.x release.

Conclusion

I am not sure how long this will take me, but I can imagine it being 1-2 quarters, given I find a few hours a week to work on it.

If you actually read all this, amazing, thank you! <3 Let me know your thoughts.

[aaronadamsCA]

Congrats on joining The Guild and thanks for the update! The core improvements sound great, as does a stable release that can drop into place with minimal migration.

Of course my hope is that Graffle could eventually replace our entire GraphQL toolchain:

• For dev/tests/stories, I already talked about how GraphQL Tools mocking + in-memory transport could help us remove MSW and stop mocking every individual operation, which would be a huge win.

• From there, I think the Graffle document builder could replace the rest of GraphQL Codegen and the GraphQL ESLint plugin and the GraphQL VS Code extension and all of the complex configuration that ties them together during dev, check, and build. This would eliminate entire categories of dependencies, frustrations and mistakes.

---

I have one interesting idea to share, sometimes you may have already thought of yourself while you were down in the "rabbit hole". Increasingly I find myself wanting to transform a type wherever it occurs in a response, e.g. always decoding Price to a locale-aware string. What if, similar to scalar(), I could define a decoder for a GraphQL type:

const graffle = Graffle
  .create({ schemaMap })
  .scalar(`Date`, {
    decode: (value) => new globalThis.Date(value),
    encode: (value) => value.toISOString(),
  })
  .type(`Price`, (value) => formatPrice(value))

I haven't fully thought through the potential ramifications, but it seemed worth sharing.

[jasonkuhrt]

I haven't fully thought through the potential ramifications, but it seemed worth sharing.

We could definitely do that! It reminds me a bit of schema extensions. The cool thing about letting Graffle do this is that you do it once and it's done, wherever you use that data type from any query result. That's why custom scalar codecs are great too. But I hadn't gone as far as to think about them more generically. An issue for this idea is welcome :)!

[P4sca1]

Hey @jasonkuhrt,
thank you again for your continued effort on graffle. I am currently in the process of migrating my codebase from graphql-request v6 + @graphql-codegen/typescript-graphql-request to graffle@next.

I am using GraphQL fragments a lot, both for selection set sharing, and for getting TypeScript types for a selection subset. I found a way to get TypeScript-native fragments using graffle. Maybe this approach can also be useful for other people migrating from graphql codegen.

// graphql/fragments/AuthenticatedUser.ts
import type { Select } from '../generated/client/modules/select'
import type * as SelectionSets from '../generated/client/modules/selection-sets'
import { GameServerListEntryFragment } from './GameServerListEntry' // import another fragment

export const AuthenticatedUserFragment = {
	id: true,
	_id: true,
	username: true,
	email: true,
	crispToken: true,
	crispEmailSignature: true,
	crispSegments: true,
	realRole: true,
	verified: true,
	registeredAt: true,
	gameServers: {
		$: { where: { reservation: false, pinned: true }, first: 10 },
		edges: {
			node: {
				...GameServerListEntryFragment,
			},
		},
	},
} satisfies SelectionSets.User

export type AuthenticatedUser = Select.User<typeof AuthenticatedUserFragment>

The neat thing is that you can import fragments everywhere you need them and use them in a similar way as you would in GraphQL using the object spread syntax (...).

[P4sca1]

The migration process is very smooth so far - far better compared to last year when I tried the migration for the first time. I stumbled across the following issues:

• Wrong type for custom scalar (e.g. Date) #1338
• client/modules/scalar.ts causes runtime errors when using custom scalars #1337

[P4sca1]

The fragment approach mentioned above can lead to a TypeScript memory leak for some reason. Type checking takes forever and eventually fails with a Heap out of memory exception.
I noticed this when using the fragment type as an input for another generic type.
A way to generate flat fragment interfaces would be great.

[jasonkuhrt]

That's great to know, i would like to eventually explore if there is something Graffle can do to make this perform optimally as much as it can.

[jasonkuhrt]

I will make no claims about velocity but I will feel good for sustaining focus: #1314. Finally merged. I will be working hard to avoid ever going down a rabbit hole that deep again in one PR. 632 files changed! (haha much of that is generated code for website and tests, but its still 100-200 manually edited files) Phew!

[P4sca1]

Congratulations on the merge! 🥳