RFC: Support both introspection.ts and graphql-env.d.ts

[ericclemmons]

Summary

urql requires a schema introspection object for Schema Awareness. (It vastly improves the DX for inferring __typename, optional vs. required, etc.)

However, it's only possible to have the .d.ts or .ts file, not both:

https://gql-tada.0no.co/reference/graphqlsp-config#tadaoutputlocation

Proposed Solution

When providing a directory value (e.g. ./src/graphql), both introspection.ts and graphql-env.d.ts (new) are created.

To explicitly create one or the other, the user can choose to provide an explicit path as indicated in https://gql-tada.0no.co/reference/graphqlsp-config#tadaoutputlocation.

Requirements

Looks like updating the following to do an isDir check & then repeating the same logic for 2 preset fileType values:

gql.tada/packages/cli-utils/src/tada.ts

Lines 41 to 47 in df302c7

	const contents = outputIntrospectionFile(minifyIntrospection(introspection), {
	fileType: outputLocation,
	shouldPreprocess,
	});
	const resolvedOutputLocation = path.resolve(base, outputLocation);
	await fs.writeFile(resolvedOutputLocation, contents);

[kitten]

We're currently working on the CLI, and I think you can expect it to be integrated and solved there, by using a generate command to separately generate the file.

I'll leave this RFC open with the proposal to treat it as a kind of addendum to #76.

---

Besides that, to address the underlying concern,

We've actually been working on slowly fading out the need for schema awareness in Graphcache. The reason is that while it's not outright a bad approach it has the huge downside that it can increase the runtime size of applications to an unreasonable scale, depending on schema size. By the time schema awareness was becoming expected (basically for interface types being detected correctly) a schema was already at a size where it became unreasonable to include it in the client bundle.

This really puts an unreasonable decision on most users of Graphcache, when you eventually approach the limits and assumptions of “schema-less” Graphcache:

• Eventually, you have to include schema awareness to fix union/interface issues, but the schema grows too large to include on the client-side
• Or, you forgo it because the schema is too large, but you have to work around these issues and ignore features like automatic partial results and offline support.

Both choices aren't great.

That's why we've been slowly working on changing this. While we don't have a comprehensive plan for offline support yet (since I don't think we have the necessary feedback/info to ensure this is safe), the other two points that required schema awareness are slowly changing.

You basically don't need automatic partial results any longer. Instead, @_optional and @_required as client-side directives are now an alternative, mirroring what client-specified nullability was supposed to do, which is/was an RFC to GraphQL itself.
These are also supported in gql.tada.

The other changes we've made address union/interface types. In the latest major of Graphcache we started to change how union/interface types are stored, supplementing schema heuristics with an internal map of which types matched.
We also know that we could comprehensively solve this problem by adding aliased typename fields onto fragments. However, we'd consider this a little unexpected by users.

That said, we believe that schema awareness will not be a “necessary evil” anymore in Graphcache going forward.

I'm aware that that doesn't address type-gen and GCG’s preset for Graphcache, which is something we're still looking to eventually replace with gql.tada too, but that will have to wait for a bit.

[kitten]

The CLI has now been released.
Specifically, it's now possible to generate a separate output, regardless of the tadaOutputLocation option in your configuration, by calling the generate-output command with the -o option, e.g.:

gql.tada generate-output -o introspection.ts