prisma-labs/graphqlgen

⚙️ Generate type-safe resolvers based upon your GraphQL Schema

graphqlgen

Generate & scaffold type-safe resolvers based on your GraphQL Schema in TypeScript, Flow & Reason

Deprecation note

graphqlgen has been officially deprecated in favor of the The Guild's project GraphQL Code Generator. Learn more about the collaboration of Prisma and the Guild in this blog post.

---

• About
  • Highlights
  • Motivation
  • Supported languages
• Getting started
  • Try out a project initializer
  • Add to existing project
  • Documentation
• Addendum
  • Community
  • Project Status
  • Prior Art

About

Highlights

• Schema-first Design in SDL to derive ideal types
• Type-safety Resolvers with precise signatures including parent, args and return type
• DX Precise resolver types puts your editor intellisense to work
• Ecosystem Interop codegen suitable for Yoga 1 or Apollo Server and supports prettier and graphql-import out of the box

Motivation

Programming in type-safe environments can contribute toward great confidence in your code's integrity. graphqlgen aims to leverage the GraphQL type system to make your resolvers completely type-safe. This is important because resolvers are the heart of any graphql service and yet the hardest to statically type due to their dynaminism.

Supported languages

• TypeScript
• Flow

Others under discussion:

• reason

Getting started

Try out a project initializer

1. Run initializer

   yarn create graphqlgen my-app # npm init graphqlgen my-app
   cd my-app
   yarn start # npm run start

2. Edit ./my-app/src/schema.graphql to your heart's content.

3. Generate types:

   yarn graphqlgen
   

Add to existing project

yarn add --dev graphqlgen # npm install --save-dev graphqlgen

Then you will have access to the cli (gg or graphqlgen):

yarn -s gg --help # npm run gg --help

Usage: graphqlgen or gg

Options:
  -i, --init     Initialize a graphqlgen.yml file
  -v, --version  Show version number                                   [boolean]
  -h, --help     Show help                                             [boolean]

gg depends on the presence of a graphqlgen.yml config located in the directory where gg is invoked. Here is an example:

language: typescript
schema: ./src/schema.graphql
context: ./src/context.ts:Context
output: ./src/generated/graphqlgen.ts
models:
  files:
    - ./src/generated/prisma-client/index.ts

Documentation

https://oss.prisma.io/graphqlgen

Addendum

Community

Join us at #graphqlgen in our Slack group and if you have more fleshed out ideas, bug reports etc. create a Github issue:

• feature request
• bug report

Project Status

graphqlgen is still in early stage development where breaking changes and tool design are a fluid matter. Feedback is deeply appreciated. You may feel comfortable giving it a try on production systems since there is no runtime aspect and hence quite safe to do so (save for a few optional default resolvers).

Prior Art

• gqlgen is the Golang equivalent of graphqlgen and served as a source of inspiration
• graphql-code-generator is a similar tool based on templates support both frontend & backend

graphqlgen's Issues

Make IResolvers compatible with IResolvers from graphql-tools

TypeError: Cannot read property 'name' of undefined

Description

I'm getting the the following error.
I think the problem is that the index of inputTypesMap should be a string but in my case typeToInputTypeAssociation[type.name] is an array.

You can find the affected line here.

Steps to reproduce

I think it's reproducible by adding something like this to the datamodel.prisma:

type Team {
  id: ID! @unique
  members: [User!]!
  calendar: [Calendar!]!
}

Expected results

No error is thrown

Actual results

Error in my console:

(node:72993) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'name' of undefined
    at /Users/sapkra/Documents/git/server/node_modules/graphql-resolver-codegen/dist/generators/ts-generator.js:80:282
    at Array.map (<anonymous>)
    at Object.generate (/Users/sapkra/Documents/git/server/node_modules/graphql-resolver-codegen/dist/generators/ts-generator.js:80:10)
    at generateCode (/Users/sapkra/Documents/git/server/node_modules/graphql-resolver-codegen/dist/index.js:87:28)
    at /Users/sapkra/Documents/git/server/node_modules/graphql-resolver-codegen/dist/index.js:181:28
    at step (/Users/sapkra/Documents/git/server/node_modules/graphql-resolver-codegen/dist/index.js:33:23)
    at Object.next (/Users/sapkra/Documents/git/server/node_modules/graphql-resolver-codegen/dist/index.js:14:53)
    at fulfilled (/Users/sapkra/Documents/git/server/node_modules/graphql-resolver-codegen/dist/index.js:5:58)
    at <anonymous>
(node:72993) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:72993) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

After that I also checked the content of the variables.
type.name = 'Team'
typeToInputTypeAssociation[type.name] = [ 'UserWhereInput', 'CalendarWhereInput' ]

Versions

• graphql-resolver-codegen: 0.3.0
• OS name and version: Mac OS 10.14

Create example

Create a new directory example with a small example app

Custom Scalar Error: Type '"JsonRoot"' cannot be used to index type 'T'.

schema.graphql

scalar Json

type AddMemberPayload {
  json: Json,
}

input AddMemberData {
  email: String!
  projects: [ID!]!
}

type Mutation {
  addMember(data: AddMemberData!): AddMemberPayload!
}

Output

import { GraphQLResolveInfo } from "graphql";

export interface ResolverFn<Root, Args, Ctx, Payload> {
  (root: Root, args: Args, ctx: Ctx, info: GraphQLResolveInfo):
    | Payload
    | Promise<Payload>;
}

export interface ITypes {
  Context: any;

  MutationRoot: any;
  AddMemberPayloadRoot: any;
}

export namespace IMutation {
  export interface ArgsAddMember {
    data: T["AddMemberPayloadRoot"];
  }

  export type AddMemberResolver<T extends ITypes> = ResolverFn<
    T["MutationRoot"],
    {},
    T["Context"],
    T["AddMemberPayloadRoot"]
  >;

  export interface Resolver<T extends ITypes> {
    addMember: AddMemberResolver<T>;
  }
}

export namespace IAddMemberPayload {
  export type JsonResolver<T extends ITypes> = ResolverFn<
    T["AddMemberPayloadRoot"],
    {},
    T["Context"],
    T["JsonRoot"]
  >;

  export interface Resolver<T extends ITypes> {
    json: JsonResolver<T>;
  }
}

export interface IResolvers<T extends ITypes> {
  Mutation: IMutation.Resolver<T>;
  AddMemberPayload: IAddMemberPayload.Resolver<T>;
}

Error

  export type JsonResolver<T extends ITypes> = ResolverFn<
    T["AddMemberPayloadRoot"],
    {},
    T["Context"],
    // Error: Type '"JsonRoot"' cannot be used to index type 'T'.
    T["JsonRoot"]
  >;

Support GraphQL directives to configure models

Hey 👋,

We thought it would make the most sense to have a direct one-to-one mapping of models and schema type declarations. We also fidgeted a bit with the idea of @model(path: "pathtomodel.ts:Model") directive syntax but thought it would be too conventional for the first version, and that we could implement it as this package evolves.

I also added a sample code of our current approach but would love to hear other ideas as well. 🙌

  User: ./src/generated/prisma-client/index.ts:UserNode
  Post: ./src/generated/prisma-client/index.ts:PostNode

Wildcard model import (based on variables)

Hey 👋,

It might be a good idea to add support for flexible imports for importing models. This could turn out super useful for recognising design patterns which could help us make design decisions in the future. However, this might be problematic since you would have to follow your own conventions.

What do you think 🙂

Make types.ts path optionally configurable

Make types.ts path configurable but keep same default

Remove import linebreaks from generated types.ts file

Make `context` config option optional and default to `any`

• Update in JSON schema
• Implement functionality

Do not append "Root" with enum and union

This is to be done in both scaffolding and interface generation.

While is is possible with current representation of GraphQL schema in TS types because template has all types, unions, enums available and can be intersected to derive the information.

A better solution for this would be to add additional information in representation of the field like isEnum, isScalar and the type definition.

This would enable us to write easier logic in template when treating different named types differently.

Create issue templates

For feature requests, bug reports etc

In bug reports, ask for graphql-resolver-codegen (graphql-resolver-codegen --version) version, OS name and version.

Name of the file containing generated interfaces and classes

Hey 👋,

Currently, output file containing generated interfaces and classes holds the name of interfaces.ts but since it could also include the abstract classes definitions its name might be misleading.

We thought about output.types but maybe you find a better idea! 🙂

Nullable field causing type assignment error

Hey @divyenduz @timsuchanek
Steps to reproduce

Use below schema.graphql and yield fresh interfaces and scaffold.

type Query {
  me: User
}

type Mutation {
  signup(name: String!, email: String!, password: String!): AuthPayload!
  login(email: String!, password: String!): AuthPayload!
}

type AuthPayload {
  token: String!
  user: User!
}

# The `User` type is a reduced version ("mask") of the `User` type from the data model (and database schema).
# It does not expose the `createdAt`, `updatedAt` and `password` fields.
type User {
  id: ID!
  email: String!
  name: String
}

Following type error is produced

{
	"resource": "/c:/Users/jas/play/prt2/src/resolvers/User.ts",
	"owner": "typescript",
	"code": "2322",
	"severity": 8,
	"message": "Type '(parent: UserParent) => string | undefined' is not assignable to type '(parent: UserParent, args: {}, ctx: Context, info: GraphQLResolveInfo) => string | Promise<string | null> | null'.\n  Type 'string | undefined' is not assignable to type 'string | Promise<string | null> | null'.\n    Type 'undefined' is not assignable to type 'string | Promise<string | null> | null'.",
	"source": "ts",
	"startLineNumber": 13,
	"startColumn": 3,
	"endLineNumber": 13,
	"endColumn": 7,
	"relatedInformation": [
		{
			"startLineNumber": 138,
			"startColumn": 5,
			"endLineNumber": 138,
			"endColumn": 9,
			"message": "The expected type comes from property 'name' which is declared here on type 'Type<TypeMap>'",
			"resource": "/c:/Users/jas/play/prt2/src/generated/resolvers.ts"
		}
	]
}

Implement `create-graphqlgen` flow

Scaffolding of new file doesn't work

For the following schema I'm about to add a new type:

type Query {
  masters(first: Int): [SpecialMaster!]!
}

type SpecialMaster {
  id: String!
  catBrothers: [Cat!]!
}

type Cat {
  id: ID!
  name: String!
  color: String!
  favBrother: Cat
}

# new type
type Dog {
  name: String!
}

The existing file structure looks like this:

Bug: The src/resolvers/Dog.ts file isn't generated and I get the following CLI output:

Suggested API enhancements in code generation

• rename root -> parent
• rename types.ts -> typemap.ts
• in-line resolver functions in place of the associative type lookup (needs an example between current and new API)
• move context.ts and typemap.ts file from resolvers folder to types folder
• Change namespaces naming convention and usage

Reason resolver scaffolding

This PR #4 implemented the feature for TS and can be used as a reference for reason.

Improve test suite via language specific validations

Description

Currently, this project relies on snapshot testing for code generation, while that is a nice approach it does not guarantee that the output code is valid in that language. We should introduce test suite that actually tried to compile the projects.

Additional context

We use prettier for some projects, which does this to some extent (before snapshot i.e. dev time) but proper solution is to run compile commands of various languages in CI.

Refactor: Make `input.context` fully dynamic

The current parsing of input.context is partially hardcoded (e.g. assumes { Context }). We should fully refactor this behavior and implement a fully tested parser of the ./my/path/file.ts:ExportedThing syntax.

Scaffold import for Context in TypeMap has a case typo

import { Context } from './context' should be import { Context } from './Context'

This causes a typing error in case-sensitive file systems.

Compose a logo for graphqlgen

Hey 👋,

I think the logo should reflect the intent of this package; maybe we could have something connected with scaffolding or generation. I like the idea of a small construction site or a craftsman doing its job. Would love to hear other thoughts on this as well, maybe you think differently about the message of this package? 🙂

Flexible export configuration syntax

Hey 👋,

We think that we'll eventually need a more sophisticated mechanism to define output.resolvers and output.models. An opinionated mechanism is an option but we should aim for good defaults rather than making such decisions at the current stage of graphqlgen

We thought something similar to {typeName} could work quite nicely but there might be a better solution. 🙂

Always override types.ts file

Always override types.ts file. Also if no -f flag is provided.

Incorrect behavior when generating "args" interface if the argument is an enumeration

Bug description

Error in file ./generated/resolver.ts: Cannot find name 'T'

export namespace QueryResolvers {
  export interface ArgsUsers {
    orderBy: T["UsersOrderByInput"] | null;
  }
}

To Reproduce

Add new test enum-import.graphql:

enum UsersOrderByInput {
  name_ASC
  name_DESC
}

type Query {
  users(orderBy: UsersOrderByInput): [User!]!
}

Expected behavior

./generated/resolver.ts

enum UsersOrderByInput {
  "name_ASC",
  "name_DESC"
}
// ...
export namespace QueryResolvers {
  export interface ArgsUsers {
    orderBy: UsersOrderByInput | null;
  }
}

Additional context
A similar error occurs for related fields:

./src/schema.graphql

enum MessagesOrderByInput {
  createdAt_ASC
  createdAt_DESC
}
# ...
type User {
  id: ID!
  # ...
  receivedMessages(orderBy: MessagesOrderByInput): [Message!]!
}

./generated/resolver.ts

export namespace UserResolvers {
  export interface ArgsReceivedMessages {
    orderBy: T["MessageOrderByInput"] | null;
  }
}

Versions:

• graphql-resolver-codegen - 0.2.4

types.ts: import Context instead of export

Update a specific resolver via scaffold

Currently, scaffold command does not override existing resolvers but has a --force or -f flag option to override all resolvers.

Sometimes, we might want to update a specific resolver, the CLI should help in achieving that.

Support plugin system

Hey 👋,

We think it would be possible to support some kind of plugin system in the future but don't yet know how that would exactly work. I think we should just drop ideas and example use cases here to get the idea of our expectations.

All the ideas are welcome 🙌

Idea: Support `gql` tag type generation

graphqlgen-starter missing config file

No need for types/Context.ts

If context is exported from context.ts, then we can just infer type, fe:

see prisma-labs/graphql-prisma-typescript#337

// context.ts

import { ContextParameters } from 'graphql-yoga/dist/types'
import { IncomingHttpHeaders } from 'http'
import * as jwt from 'jsonwebtoken'

import { prisma } from './prisma'

const getUserId = (authorization: IncomingHttpHeaders['authorization']) => {
  const re = new RegExp('^Bearer ')

  return () => {
    if (re.test(authorization)) {
      const [, token] = authorization.split(re, 2)

      const { userId } = jwt.verify(token, process.env.APP_SECRET!) as {
        userId: string
      }

      return userId
    }

    throw new Error('Unauthorized')
  }
}

export const context = ({ request }: ContextParameters) => {
  return {
    db: prisma,
    getUserId: getUserId(request.headers.authorization),
  }
}

// types/TypeMap.ts

export interface TypeMap extends ITypeMap {
  Context: ReturnType<typeof import('../../context').context>
  // ...
}

Implement helpful error messages

Process

• Design propsoal in Figma
• Implement in graphqlgen

Cases

• graphqlgen.yml file not found
• Missing config option in graphqlgen.yml
• Invalid GraphQL schema
• Couldn't parse imported source definitions (i.e. models, context)
• Model missing in models based on existing GraphQL type definition

Friction & areas to improve

• Keep actual resolver object up to date
• resolver files and type definitions should live in different directories
• Initial setup: Configure with GraphQL server (GraphQL Yoga/Apollo Server)

Cannot find module './generators/ts-generator' in 0.2.3

In 0.2.3 it's throwing this error:

$ graphql-resolver-codegen interfaces -s src/schema.graphql -o src/generated/resolvers.ts
internal/modules/cjs/loader.js:583
    throw err;
    ^

Error: Cannot find module './generators/ts-generator'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:581:15)
    at Function.Module._load (internal/modules/cjs/loader.js:507:25)
    at Module.require (internal/modules/cjs/loader.js:637:17)
    at require (internal/modules/cjs/helpers.js:20:18)
    at Object.<anonymous> (/Users/.../node_modules/graphql-resolver-codegen/dist/index.js:48:22)
    at Module._compile (internal/modules/cjs/loader.js:689:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)
    at Module.load (internal/modules/cjs/loader.js:599:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)
    at Function.Module._load (internal/modules/cjs/loader.js:530:3)

Cannot find name 'T'

The generated types contain a typescript error, Cannot find name 'T'.

Steps to reproduce...

schema.graphql

type AddMemberPayload {
  newUserId: ID,
  existingUserInviteSent: Boolean
}

input AddMemberData {
  email: String!
  projects: [ID!]!
}

type Mutation {
  addMember(data: AddMemberData!): AddMemberPayload!
}

Run

graphql-resolver-codegen interfaces -s schema.graphql

Outputted types

import { GraphQLResolveInfo } from "graphql";

export interface ResolverFn<Root, Args, Ctx, Payload> {
  (root: Root, args: Args, ctx: Ctx, info: GraphQLResolveInfo):
    | Payload
    | Promise<Payload>;
}

export interface ITypes {
  Context: any;

  MutationRoot: any;
  AddMemberPayloadRoot: any;
}

export namespace IMutation {
  export interface ArgsAddMember {
    data: T["AddMemberPayloadRoot"];
  }

  export type AddMemberResolver<T extends ITypes> = ResolverFn<
    T["MutationRoot"],
    {},
    T["Context"],
    T["AddMemberPayloadRoot"]
  >;

  export interface Resolver<T extends ITypes> {
    addMember: AddMemberResolver<T>;
  }
}

export namespace IAddMemberPayload {
  export type NewUserIdResolver<T extends ITypes> = ResolverFn<
    T["AddMemberPayloadRoot"],
    {},
    T["Context"],
    string
  >;

  export type ExistingUserInviteSentResolver<T extends ITypes> = ResolverFn<
    T["AddMemberPayloadRoot"],
    {},
    T["Context"],
    boolean
  >;

  export interface Resolver<T extends ITypes> {
    newUserId: NewUserIdResolver<T>;
    existingUserInviteSent: ExistingUserInviteSentResolver<T>;
  }
}

export interface IResolvers<T extends ITypes> {
  Mutation: IMutation.Resolver<T>;
  AddMemberPayload: IAddMemberPayload.Resolver<T>;
}

The types that is failing from the above is...

 export interface ArgsAddMember {
    // error TS2304: Cannot find name 'T'.
    data: T["AddMemberPayloadRoot"];
  }

If I add

type T = ITypes

Everything works

TS-Generator: Nullable fields & strict mode

Description

The generated [Type]Parent interface is compatible with typescript's --strictNullChecks setting if the type includes an optional field. With --strictNullChecks enabled, null and undefined are treated as different values.

The related issue that is now causing the break:
#25

Steps to reproduce

type User {
  name: String
}

type Query {
  user: User
}

Expected results

Should produce a resolver type that allows for undefined values

export namespace UserResolvers {
  export type NameType<T extends ITypeMap> = (
    parent: T['UserParent'],
    args: {},
    ctx: T['Context'],
    info: GraphQLResolveInfo
  ) => string | Promise<string | null | undefined> | null | undefined;

Actual results

export namespace UserResolvers {
  export type NameType<T extends ITypeMap> = (
    parent: T['UserParent'],
    args: {},
    ctx: T['Context'],
    info: GraphQLResolveInfo
  ) => string | Promise<string> | null ;

Versions

• graphql-resolver-codegen: 0.3.1

Make return of resolver dynamic

Because it is ;)

Special behavior for Query, Mutation and Subscription root types + resolvers

It's very common for the initial root value (i.e. provided to the graphql function) to be non-empty. I therefore suggest to adjust the behavior for the Query, Mutation, and Subscription root types:

1. Empty root types:

export interface QueryRoot {}
export interface MutationRoot {}
export interface SubscriptionRoot {}

2. Empty/null value default resolvers:

export const Query: IQuery.Resolver<Types> = {
  optionalField: (root, args, ctx) => null,
  requiredList: (root, args, ctx) => [],
  requiredString: (root, args, ctx) => "",
  requiredNumber: (root, args, ctx) => 0,
  requiredBool: (root, args, ctx) => false,
  requiredObjectType: (root, args, ctx) => {
    throw new Error('Resolver not implemented')
  },
}

Use ? for nullable fields

If you have a type that includes an optional field, the following is generated right now:

export interface PlaceRoot {
  id: string
  name: string
  size: PLACE_SIZES | null
  maxGuests: number
}

This means that the resolver needs to return an explicit null value:

const resolvers = {
  size: () => null
}

However, graphqljs allows returning undefined for a nullable value.
This makes implementations easier, as we don't need to return an explicit null anymore.

To make this possible, the only difference is turning | null into ?:

export interface PlaceRoot {
  id: string
  name: string
  size?: PLACE_SIZES
  maxGuests: number
}

I just tested it in TypeScript 2.9.2 - ? allows both undefined and null.

Document `interfaces` and `scaffold` command individually in README

Referenced 'AssetCreateManyInput' populating with the wrong types

Description

I have a custom mutation to create an Account with the option to simultaneously create or connect existing Assets to be bound to that Account. I provide a parameter in my mutation function called 'assets' that has a type of AssetCreateManyInput (which should be imported from my generated prisma.graphql schema). Generating the interfaces from my schema.graphql gives the wrong property types for AssetCreateManyInput.

Steps to reproduce

I have these types in my schema.graphql, that reflect and omit some values from my datamodel.graphql:

type Account {
  id: ID!
  company: String!
  isLockedOut: Boolean
  users: [User!]!
  assets: [Asset!]!
}

type Asset {
  assetId: String!
  assetType: AssetType
  users: [UserAssetConfig!]!
}

I have a mutation that creates an Account, User, and optionally connects/creates Assets

type Mutation {
  createAccount(email: String!, company: String!, accountType: AccountType, assets: AssetCreateManyInput): Account
}

My schema.graphql also imports the generated prisma.graphql file # import * from "./generated/prisma.graphql"

I then run graphql-resolver-codegen interfaces -s src/schema.graphql -o ./src/generated/resolvers.ts

Expected results

In resolvers.ts I expect to see something like what is generated in my prisma-client/index.ts:

export interface AssetCreateManyInput {
  create?: AssetCreateInput[] | AssetCreateInput;
  connect?: AssetWhereUniqueInput[] | AssetWhereUniqueInput;
}

Actual results

In resolvers.ts I actually see an interface that looks like this:

  export interface AssetCreateManyInput {
    create: string;
    connect: string;
  }

This causes type casting issues when I'm trying to write my mutation resolver in Typescript.

Versions

• graphql-resolver-codegen: 0.3.0
• OS name and version: Windows 10

Types for Subscriptions are not correct

Currently generating types for GraphQL subscriptions are the same as Query, Mutation. Subscription resolvers have a different structure.

Support for nested input types

Codegen does not generate types for nested input object types. It should handle that case better.

Related issue: #29

Rethink scaffolding

• Adjust/fix import path
• Remove generation of types file/folder
• Specify folder + "style" instead of file path -> allows for deletion of previously scaffolded files

Support for flow

The CLI provides generators for reason, typescript and similarly generator for flow can be added. A generator is a JS file that exports generate and format function.

Examples - TS, Reason

Split example into examples with path for each language - currently, reason, typescript.

Unhelpful TS compiler message (Suggests `then` instead of actual missing field)

Schema-based model imports via directives

Support model path definitions using @model(path: "") syntax.

type Post @model(path: "./models/post.ts:Post") {
  id: ID!
  title: String!
}

Something we should consider as well are default values; should we support ./models/post.ts alongside ./models/post.ts:Post? What do you think?

Add "DO NOT EDIT!" comment to `resolvers.ts` file

Interfaces path to be friendlier

Currently, the scaffold command gets the path to interfaces via -i argument. The value of this argument should be relative to -o (output) path supplied to scaffold command.

While this is explicit, we can also support -i path as path from src directory and dynamically find out relative path.

Support for custom scalars

Codegen does not generate types for specific custom scalars yet. Things like DateTime, Json produce unexpected results.

Codegen should handle that gracefully.