Very early v8 feedback

[aaronadamsCA]

Hey @jasonkuhrt, I've started to explore Graffle and I have feedback and questions.

It's an exciting project because I'm pretty sure Graffle could eventually replace a boatload of tooling in our repo, including graphql-codegen, graphql-config, @graphql-eslint/eslint-plugin, and possibly even msw.

I think migration would go something like this:

1. Swap graphql-request for graffle using a static client and typed document nodes.
2. Replace the static client with a generated client.
3. Gradually rewrite operations (and their mocks!) to use the generated client.
4. Remove all of the legacy tooling.

I tried playing around with the library today and ran into a few early trouble spots:

• Not sure how to migrate the return type of our existing createClient(): GraphQLClient signature.
• client.raw({ document }) doesn't seem to be compatible with TypedDocumentNode from @graphql-typed-document-node/core, so I can't use existing documents generated by graphql-codegen.
• The CLI crashes due to a missing dependency on json-bigint (adding the dependency works around the issue).
• Custom scalars seem to break the generated client. Specifically it looks like Global.ts maps custom scalars to StandardScalar.String, but the scalar imports are wrong so the module breaks.

I'm also curious about mocking responses. We currently share typed document nodes between graphql-request and msw, which can be painful; every operation change requires regenerating documents and updating mock responses, plus it's hard to get MSW working at all in certain environments.

Since a Graffle generated client knows nothing about operations, I'm guessing the approach here would instead involve mocking an in-memory schema? If so, it would be great if we could use the generated HTTP client to help create the mock, so we could get type safety and skip all the GraphQLSchema boilerplate.

[jasonkuhrt]

Hey @aaronadamsCA thanks for the feedback! I really appreciate it. I'll take up your issues one by one.

Not sure how to migrate the return type of our existing createClient(): GraphQLClient signature.

Ideally this should be really easy. Was/is https://graffle.js.org/guides/misc/output helpful for you? I've noted in #1024 to have add a migration guide.

client.raw({ document }) doesn't seem to be compatible with TypedDocumentNode from @graphql-typed-document-node/core, so I can't use existing documents generated by graphql-codegen.

This should also just work but I understand why it is not. I am aware of dotansimha/graphql-typed-document-node#68. Graffle is using https://graphql-js.org/api/interface/TypedQueryDocumentNode which is newer and in theory more community friendly because of its community core position. Hey @dotansimha could you weigh in on this, since that issue I referenced is multiple years old now. Are there plans to modernize around newer versions of graphql? Meanwhile I've made an issue to track this, maybe Graffle can support both or something: #1154.

The CLI crashes due to a missing dependency on json-bigint (adding the dependency works around the issue).

Can you share more about this one? Graffle doesn't use that library 🤔.

Custom scalars seem to break the generated client. Specifically it looks like Global.ts maps custom scalars to StandardScalar.String, but the scalar imports are wrong so the module breaks.

I'm actively working on simplifying whilst also making more powerful the customer scalar story for Graffle. Stay tuned, hopefully will wrap up all the changes by end of next week including new docs and test coverage. The issues are a bit messy for this but related are: #1150, #1149.

I'm also curious about mocking responses.

There's lots to say here.

• You could use use Anyware to return mocked responses though that might be too blunt.
• You could create an in-memory schema that mocks at the level of resolvers.
• Perhaps various bits of Graffle could be composed with other tools. For example maybe you use the generated client select module to write type-safe documents but then handle their execution with some other tool. If there were a need to use Graffle to write documents instead of execute them I would want that to be easy. For example internally Graffle typed interface gets translated into a vanilla graphql document before getting sent over the wire. It would be trivial to expose a utility function designed just to emit that for other tooling/use-cases.
• ...

I'm not sure I follow your own thoughts about mocking in your setup, happy to hear more.

[aaronadamsCA]

Super helpful, thanks! I'll make my way through your response over the next little bit.

There are a few references to json-bigint in the generator layer: https://github.com/search?q=repo:jasonkuhrt/graffle%20json-bigint&type=code

In terms of mocks, I'm not even sure I follow my own thoughts yet. 😅 But I'll try to quickly clarify—and based on your response, I'm pretty sure we're already on the same page:

• A graphql-codegen "client" is not a general-purpose client; it's a bunch of typed document nodes generated from our operations, and we need to regenerate them every time we add/change an operation.
  • Mocking with MSW is based on those typed document nodes (or operation names).
• By comparison, Graffle generates a true client, so there's nothing to regenerate after adding or changing an operation.

I've had today to noodle this, and I think something like this could work really well:

• Generate a real client from your real graph with Graffle.
• Import a GraphQLSchema instance (or at least an SDL string or introspection JSON) from the generated client.
• Use addMocksToSchema to create your own in-memory schema with your own resolvers.
• Pass the mock schema back to Graffle.create().
• Create as many mock schemas as you want!

Presumably the real client and the mock schemas would have compatible types, and you'd have multiple means available to switch between them—whatever worked best for your use case.

[marcospassos]

Same issue here:

[jasonkuhrt]

I've had today to noodle this, and I think something like this could work really well:

I'm not familiar with https://the-guild.dev/graphql/tools/docs/mocking but yep that sounds entirely doable what you're thinking!

[jasonkuhrt]

@aaronadamsCA once #1165 is merged the issue about typed document node not working will be resolved. That will land early next week.

[aaronadamsCA]

@jasonkuhrt I finally had some time to try out the latest build yesterday, and I can confirm all of the above issues are fixed! 🙌

I'll add a couple of comments with further questions/thoughts as we look at how best to adopt this in a medium-sized monorepo containing several apps.

[jasonkuhrt]

There are a few references to json-bigint in the generator layer: github.com/search?q=repo:jasonkuhrt/graffle%20json-bigint&type=code

@aaronadamsCA thanks for reporting that json-big-int issue, it must have crept in via auto import some time and because it was _ aslant didn't pick it up as an unused variable. Wow! Fixed in 624e684.

[aaronadamsCA]

Today we have multiple web apps in a monorepo, with each graph client in its own package.

I'd like to try to maintain this separation of responsibilities if possible. If we can encapsulate generation and mocking in our graph client packages, then our apps don't need to know those implementation details.

Let me know if you see any problems with this approach:

1. Use the Graffle CLI to generate a client from a remote schema.
2. Use (TBD) and addMocksToSchema(…) from GraphQL Tools to create a GraphQLSchema instance that returns mock data for any valid request.
3. Use Graffle to create a mock client that uses the in-memory GraphQLSchema instance.
4. Export both clients from the package.

For Step 2, it would probably be easiest if the Graffle CLI saved the result of the introspection query to a JSON file, so we could just import it to create our mock schema:

import { addMocksToSchema } from "@graphql-tools/mock";
import { Graffle } from "graffle";
import { buildClientSchema } from "graphql";

import introspectionResult from "./graffle/schema.json";

const schema = buildClientSchema(introspectionResult);

const schemaWithMocks = addMocksToSchema({
  schema,
  mocks: {},
});

export const client = Graffle.create({ schema: schemaWithMocks });

Otherwise this approach seems to work! I already created a little POC to confirm the clients can be used interchangeably, and everything seems to work so far.