ReScript GraphQL Codegen

Typed ReScript GraphQL operation code generation with first-class support for rescript-embed-lang.

Install the published generator with:

yarn add --dev @_zth/rescript-graphql-codegen

Usage

Compiled operation artifacts

Set operationModule to a ReScript module whose make function accepts ~name, ~hash, and ~getDocument. Each generated operation then exposes an operation value typed as operationModule.t<variables, t>, plus the same value as default. Variables and results are trusted from the generated operation types; runtime validation is the responsibility of the configured client, not the generated descriptor.

With rescript-embed-lang 0.6.1 or newer, the embed CLI uses its first-class GraphqlDefinition strategy to derive a stable module name from the GraphQL operation name and emits one file per operation. A value embed therefore produces the typed operation directly:

let example = %generated.gqlExternalSchema(`
  query Example($id: ID!) {
    example(id: $id) {
      id
    }
  }
`)

await client->run(example, {id})

The generated module remains available as SourceFile__gqlExternalSchema__Example when callers need its variables, result t, schemas, or operation metadata. The embed CLI writes the rescript-embed-lang.json consumed by the PPX, keeping its extraction configuration identical to codegen.

Sury schemas can be generated independently from operation execution:

{
  operationModule: "GraphqlOperation",
  surySchemaGeneration: "fromDirective"
}

Opt an operation in with the codegen-only directive:

query Example($id: ID!) @gqlGenerator__generateSurySchema {
  example(id: $id) {
    id
  }
}

The directive emits the operation's variablesSchema and output schema artifacts. It is removed before the executable document and operation hash are generated. surySchemaGeneration also accepts "always" and "never". The older generateSurySchemas boolean remains supported when the new option is omitted.

Status

Mostly done

• lib: contains
  • core-plus: Extensions around rescript-core.
  • graphql: Rescript bindings (and light wrappers) around the graphql javascript library.
  • graphql-codegen: Rescript bindings for writing graphql-codegen plugins in rescript
• base-types: Baseline Rescript codegen plugin. Generates enum and input types.
• operations: Baseline Rescript codegen plugin. Generates variable and output types.
• test: Runs generated codegen plugins

TODO

• near-re-operation-file: Planned output preset; the near-operation-file preset automatic generates Typescript imports, which need to be prevented with certain specific values in the presetConfig. Ideally, this would be a very similar equivalent that requires no special config.