Spring 🌼 Status Update

[jasonkuhrt]

My last status update in winter introduced the emergence of an opt-in type-safe ts-client layered over a raw mode that comes out of the box (equating to what graphql-request is today).

#675

I've made progress since then, primarily two things:

• The TS client, tested thoroughly both at the term and type level
• A new extension system

The TS client is in a state that is essentially ready for production usage, a first version.

However I want to get the extension system into a state that supports file upload and persisted query use-cases.

After that there are a few odds and ends like being able to generate types from an introspection query (instead of assuming you have access to a schema.graphql file). Or the fact that generated runtime code (there is a tiny bit for custom scalar support) are TS files which does not support JS users.

When this work is done, the release will launch under a new package name graffle.

I expect this to happen this year, maybe as early as September, but if not, I'll have a status update in the autumn about what has happened.

Everything I am doing is still in the graphql-request package. I welcome any alpha users that want to take the project for a spin.

I will also be working on the new docs in /DOCUMENTATION_NEXT.md.

Mo more features will be shipped for graphql-request. All effort will be going into making Graffle scale from the minimal client that graphql-request already is, up to the bleeding edge first class TypeScript experiences that I am personally passionate about.

Cheers
👋

[P4sca1]

Hello @jasonkuhrt,

thank you for your continued effort on the graphql-request library and on graffle. I just upgraded to the latest version to try out the graffle client. Documentation is definitely needed, but I managed to setup a client by looking at the source code and my first impression is very positive. Here are some things I noticed while working with graffle:

• Compilation fails when verbatimModuleSyntax is enabled, because import type is not used for type-only imports. I worked around this issue by creating a tsconfig.json in the generated client folder, which disables verbatimModuleSyntax just for that specific folder.

{
	"extends": "../../tsconfig.json",
	"compilerOptions": {
		"verbatimModuleSyntax": false
	},
	"include": ["./**/*.ts"]
}

• Formatting does not work when dprint is not installed. I think this is a good design decision to not bundle a formatter with the library. Maybe support could be extended to other formatters like prettier or biome using --format prettier for example. Or exclude formatting entirely and let it be handled by the client.
• Right now I am using graphql-codegen to pull the schema.graphql file, then run graffle, followed by my formatter:

{
  "scripts": {
    "graphql:fetch-schema": "graphql-codegen",
    "graphql:generate-client": "pnpm run graphql:fetch-schema && graffle --schema ./graphql/schema/schema.graphql --output ./graphql/client --format false --schemaErrorTypes false && prettier --write ./graphql/client"
  }
}

import type { IGraphQLConfig } from 'graphql-config'
import type { CodegenConfig } from '@graphql-codegen/cli'

export default <IGraphQLConfig>{
	schema: 'graphql/schema/schema.graphql',
	extensions: {
		codegen: <CodegenConfig>{
			generates: {
				'graphql/schema/schema.graphql': {
					schema: 'http://127.0.0.1:8080/graphql',
					documents: [],
					plugins: ['schema-ast'],
				},
			},
		},
	},
}

An integration into graphql-config would be great, as it already supports hooks to run formatting. That way everything could be generated using a single command and be configured in graphql.config.ts.

• While implementing custom scalars, I noticed that the codec function and Codec type are not exported.
• How would I create a Void and JsonObject scalar? Using graphql-codegen I st the type of Void to null and JsonObject to Record<string, unknown>. How would I do this inside graphql/schema/customScalarCodecs.ts? This is my current approach, which lacks typing.

export const JsonObject = scalar(`JsonObject`, {
	encode: (value) => value,
	decode: (value) => value,
})
export type JsonObject = typeof JsonObject

export const Void = scalar(`Void`, {
	encode: () => null,
	decode: () => null,
})
export type Void = typeof Void

• Is there a way to define a type based on GraphQL types? E.g. I have a type User (GraphQL) and based on that I would like to create a type AuthenticatedUser (TypeScript) that inherits a set of properties of the user type and is available throughout my app.
• I noticed that the default Content-Type is text/plain. I think it should be application/json. Luckily I was able to fix it using the new extension system:

export const client = create({
	schema: 'http://localhost:3000/gateway/graphql',
	returnMode: 'data',
	headers: {
		'Content-Type': 'application/json',
	},
}).extend(async ({ pack }) => {
	return pack({
		...pack.input,
		headers: {
			'Content-Type': 'application/json',
		},
	})
})

• When creating a client, I was a little bit confused that there is no url option. I think it makes sense to rename the option schema to url.

[jasonkuhrt]

Wow @P4sca1 this is a veritable treasure trove of feedback, I'm lucky and grateful for it. I am currently improving the extension system to be able to support graphql-upload spec, but as an extension rather than hard coded.

After that, I may start to tackle all these issues you've graciously QA'd. I hope that Graffle is helping you out too :).

Regarding the url/schema key in the config object, I hear ypu. I was trying to find something that would make sense for both in memory and remote schemas. Perhaps if remote schemas make up 99% of the use cases we could just use the term "url" and to heck with it. But I would prefer a cleaner solution than that if we can think of one. Ideas welcome!

[P4sca1]

I haven't thought about using the client with local schemas yet. In that case, the option name schema makes more sense. When using a local schema no outgoing requests are performed right? So the headers option would also be unneeded?
If that's the case, maybe 2 different constructors would make sense. One for local schemas and one for targetting remote GraphQL servers.

[jasonkuhrt]

Yup exactly.

I believe currently the types are a union so headers are only possible in one case. Separate constructors is a worthwhile consideration, eg "Graffle.createMemory(...)" or something. Not in love with that but something to consider.

[jasonkuhrt]

I noticed that the default Content-Type is text/plain. I think it should be application/json

This is fixed from #949. I have test coverage for it now. Thanks for reporting this!

[jasonkuhrt]

I've create a few issues:

• Support grpahql-config #948
• Compilation fails when verbatimModuleSyntax is enabled #947
• Export codec types and helpers #950

How would I create a Void and JsonObject scalar? Using graphql-codegen I st the type of Void to null and JsonObject to Record<string, unknown>. How would I do this inside graphql/schema/customScalarCodecs.ts? This is my current approach, which lacks typing.

I'll try to take some time to unpack this more. IIRC you need to pass in function type variables right now but inference would be better. I'll investigate the status of all that when I have a chance.

Is there a way to define a type based on GraphQL types? E.g. I have a type User (GraphQL) and based on that I would like to create a type AuthenticatedUser (TypeScript) that inherits a set of properties of the user type and is available throughout my app.

Do you mean a use-case like this?

import type { User } from './generated/graffle/types'
type AuthenticatedUser = User & { ... }