@eddeee888/gcg-typescript-resolver-files

This GraphQL Code Generator plugin creates resolvers given GraphQL schema.

This relies on types generated from @graphql-codegen/typescript and @graphql-codegen/typescript-resolvers plugins.

``bash
yarn add -D @graphql-codegen/cli @eddeee888/gcg-typescript-resolver-files
yarn add graphql-scalars
`

Features

- Generates opinionated folder/file structure with type-safety in mind to help finding query, mutation or object types easily
- Does _NOT_ overwrite existing resolver logic
- Detects missing / wrong resolver exports and adds them to resolver files
- Automatically sets up GraphQL Scalars with types and config from graphql-scalars with ability to opt-out
- Automatically extracts object type mapper interfaces and types (marked with Mapper suffix) from accompanying .mappers.ts files in each module. For example, if the schema file is /path/to/schema.graphql, the mapper file is /path/to/schema.mappers.ts.

Getting Started

$3

#### Files

`graphql


src/schema/base/schema.graphql

type Query

src/schema/user/schema.graphql

extend type Query {
user(id: ID!): User
}

type User {
id: ID!
fullName: String!
}

type Address {
id: ID!
address: String!
}
`

``ts
// src/schema/user/schema.mappers.ts

// Exporting the following Mapper interfaces and types is the equivalent of this codegen config:
// `yml
// mappers:
// Address: './user/schema.mappers#AddressMapper'
// User: './user/schema.mappers#UserMapper'
// `

export { Address as AddressMapper } from 'address-package';

export interface UserMapper {
id: string;
firstName: string;
lastName: string;
}
``

#### Codegen Config

`ts
// codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli';
import { defineConfig } from '@eddeee888/gcg-typescript-resolver-files';

const config: CodegenConfig = {
schema: '**/schema.graphql',
generates: {
'src/schema': defineConfig(),
},
};

export default config;
`

OR

`yml


codegen.yml


schema: '*/.graphql'
generates:
src/schema:
preset: '@eddeee888/gcg-typescript-resolver-files'
watchPattern: '*/.mappers.ts'
`

$3

Running codegen will generate the following files:

- src/schema/user/resolvers/Query/user.ts
- src/schema/user/resolvers/User.ts
- src/schema/user/resolvers/Address.ts
- src/schema/resolvers.generated.ts
- src/schema/typeDefs.generated.ts
- src/schema/types.generated.ts

Config Options

$3

merged or modules (Default: modules)

How files are collocated. modules detects containing dir of a schema file as "modules", then split resolvers into those modules. merged treats baseOutputDir as the one and only module and generates resolvers.

$3

last or first, a number, or all (Default: last)

Specifies how the plugin determines the module name for each schema file.

- last: The module name is derived from the last directory (within the schema directory) in the file's path.
- first: The module name is derived from the first directory (within the schema directory) in the file's path.
- all: The module name is derived all directories in the file's path.
- any number: The module name is derived from the nth zero-indexed directory (within the schema directory) in the file's path. Supports negative numbers which select the nth directory from the back of the file's path.

For example:

#### last

- src/schema/foo/bar/baz/User.graphql => module name is baz

#### first

- src/schema/foo/bar/baz/User.graphql => module name is foo

#### 1

- src/schema/foo/bar/baz/User.graphql => module name is bar

#### -2

- src/schema/foo/bar/baz/User.graphql => module name is bar

$3

string (Default: ./types.generated.ts)

Relative path to type file generated by typescript-resolvers plugin.

$3

string (Default: resolvers)

Relative path to target dir. For config.mode=merged, files will be generated into /. For config.mode=modules, files will be generated into /**//.

$3

merged or modules (Default: merged)

How to generate file/s that put resolvers map together:

- merged: one file
- modules: one file per module

$3

string (Default: resolvers.generated.ts)

File that puts all generated resolvers together. Relative from baseOutputDir.

$3

disabled or minimal or recommended or all or object (Default: recommended)

Decides which resolvers to generate:

- disabled: generates no resolvers. Use this if you want to use your own structures. Note: if custom scalars are detected and used, resolver main files are still generated.
- minimal: generates root-level resolvers only.
- recommended: generates root-level and object resolvers. Use this if you want a managed experience.
- no union/interface resolvers are generated because we rely on certain settings in typescript-resolvers that make these not required.
- all: generates all resolvers. Use this if you want all resolvers to be generated and use the ones you need.

Internally, each string option is turned into an object. This object uses glob pattern to tell which files to be generated based on the file's normalized name (\*). For example, recommended option is the equivalent of the following object:

`ts
{
query: '*',
mutation: '*',
subscription: '*',
scalar: '*',
object: '*',
union: '',
interface: '',
enum: '',
}
`

(\*) A normalized name has the following shape: ..?

Consider this schema:

`graphql


src/schema/pet/schema.graphql

extend type Query {
pets: [Pet!]!
}

type Cat {
id: ID!
}
type Dog {
id: ID!
}
union Pet = Cat | Dog

src/schema/user/schema.graphql

extend type Mutation {
createUser(id: ID!): CreateUserResult!
}

type User {
id: ID!
}

type CreateUserOk {
result: User!
}
type CreateUserError {
error: String!
}
union CreateUserResult = CreateUserOk | CreateUserError
`

Then, the generated files and normalised names are:

- src/schema/pet/resolvers/Query/pets.ts, affected by query option, normalized name: pet.Query.pets
- src/schema/pet/resolvers/Cat.ts, affected by object option, normalized name: pet.Cat
- src/schema/pet/resolvers/Dog.ts, affected by object option, normalized name: pet.Dog
- src/schema/pet/resolvers/Pet.ts, affected by union option, normalized name: pet.Pet
- src/schema/user/resolvers/Mutation/createUser.ts, affected by mutation option, normalized name: user.Mutation.createUser
- src/schema/user/resolvers/User.ts, affected by object option, normalized name: user.User
- src/schema/user/resolvers/CreateUserOk.ts, affected by object option, normalized name: user.CreateUserOk
- src/schema/user/resolvers/CreateUserError.ts, affected by object option, normalized name: user.CreateUserError
- src/schema/user/resolvers/CreateUserResult.ts, affected by union option, normalized name: user.CreateUserResult

Now, let's say we want to disable all union files, types ending with Ok or Error, the config would look like this:

`ts
defineConfig({
resolverGeneration: {
query: '*',
mutation: '*',
subscription: '*',
scalar: '*',
object: ['!.Ok', '!.Error'], // Disables objects ending with Ok or Error in every module
union: '', // Empty string disables all file generation of relevant type in every module
interface: '*',
},
});
`

Hint: To see why certain files are skipped, run codegen command with DEBUG turned on:

`
DEBUG="@eddeee888/gcg-typescript-resolver-files" yarn graphql-codegen
`

$3

merged or mergedWhitelisted or modules (Default: merged)

How to generate typeDefs file/s:

- merged: one file
- mergedWhitelisted: one file but only contains whitelisted modules
- modules: one file per module

If config.mode=merged, this config is always merged

$3

string or false (Default: ./typeDefs.generated.ts)

Where to generate typeDefs files. If value is false or empty string, the file/s are not generated.

If typeDefsFileMode=merged or typeDefsFileMode=mergedWhitelisted, this path is relative from baseOutputDir.

If typeDefsFileMode=modules, this path is relative from each module directory.

$3

boolean, string or object (Default:./schema.generated.graphqls)

Option to merge multiple schemas into one. Uses schema-ast plugin internally.

Unless false is used, the input is turned into the following object:

`ts
{
path: string; // path to the generated file
config: (@graphql-codegen/schema-ast).SchemaASTConfig; // Full config options can be found here: https://the-guild.dev/graphql/codegen/plugins/other/schema-ast
}
`

Note: Make sure your Codegen config's schema field does not include the generated schema file, otherwise unexpected errors may occur.

$3

Record (Default: undefined) (EXPERIMENTAL)

Allows using add plugin on a given file.

Note: Currently only supports resolverTypesPath file i.e. types.generated.ts

Example:

`ts
// codegen.ts
{
generates: {
'src/schema': defineConfig({
add: {
'./types.generated.ts': { content: '/ eslint-disable /' },
},
})
}
}
`

$3

Array (Only works with config.mode=modules)

Whitelists modules to generate files and entries in main file. By default all modules are whitelisted. Useful for gradual migrations.

$3

Array (Only works with config.mode=modules)

Blacklists modules to avoid generate files and entries in main file. Useful for gradual migrations.

$3

Record

Map of relative or absolute path (prefixed with ~) to external or existing resolvers.

Examples:

- DateTime: ~graphql-scalars#DateTimeResolver
- Query.me: '~@org/meResolver#default as meResolver'
- User: 'otherResolvers#User as UserResolver'.

$3

(@graphql-codegen/typescript).TypeScriptPluginConfig & (@graphql-codegen/typescript-resolvers).TypeScriptResolversPluginConfig

Takes typescript config and typescript-resolvers config to override the defaults.

Experimental options:

- namingConvention

$3

string (Default: ./)

By default, mappers must be siblings with the schema they represent. For example, if the schema file is /path/to/schema.graphql, the mapper file is /path/to/schema.mappers.ts. This extension allows mappers to reside in a different directory relative to the schema file using the pattern //.

$3

string (Default: .mappers.ts)

The files with this extension provides mappers interfaces and types for the schema files in the same module.

$3

string (Default: Mapper)

Exported interfaces and types with this suffix from mappersFile in each module are put into the mappers object of @graphql-codegen/typescript-resolvers.

$3

string or false (Default: graphql-scalars)

Where Scalar implementation and codegen types come from. Use false to implement your own Scalars.

If using an module that is not graphql-scalars, the module must export resolver implementation and codegen type the same way graphql-scalars does e.g.

`ts
{
resolvers: {
DateTime: DateTimeResolver,
},
DateTimeResolver: {
// ... resolver implementation
extensions: {
codegenScalarType: 'Date | string',
},
}
}
`

$3

Record (Default: {})

Overrides scalars' resolver implementation, type or both.

Example:

`ts
// codegen.ts
{
generates: {
'src/schema': defineConfig({
scalarsOverrides: {
DateTime: {
resolver: './localDateTimeResolver#Resolver',
}
Currency: {
type: 'unknown'
},
BigInt: {
resolver: '@other/scalars#BigIntResolver',
type: {
input: 'bigint',
output: 'number | string'
}
}
}
})
}
}
`

$3

string (Default: ./tsconfig.json)

Project's TypeScript config, relative from project root. This helps type analysis such as resolving custom module paths.

$3

smart or disabled or object (Default: smart) (Experimental)

smart option does static analysis and add fields to ensure no runtime errors. The default smart option is expanded to an object like this to target supported types:

`ts
{
object: 'smart',
enum: 'smart'
}
`

- For objects types: statically compares object type's mapper types' field against schema types' fields, creating resolvers if required.
- For enum types: ensure all allowed values are present.

$3

'' | .${string} (Default:'')

Specifies the file extension to use for generated imports. This allows you to control whether imports use extensions like .js, .ts, .mjs, etc.

Examples:

- '' - No extension (CommonJS-style imports)
- '.js' - ESM-style with .js extension
- '.ts' - TypeScript-style with .ts extension
- '.mjs' - ESM with .mjs extension

Root-level inheritance: You can set importExtension at the root level of your GraphQL Codegen config, and it will be inherited by all generates blocks that use this preset. Preset-level configuration will override root-level configuration.

`typescript
import type { CodegenConfig } from '@graphql-codegen/cli';
import { defineConfig } from '@eddeee888/gcg-typescript-resolver-files';

const config: CodegenConfig = {
schema: 'src/schema/**/schema.graphql',
importExtension: '.ts', // Root-level - inherited by all generates blocks
generates: {
'src/schema': defineConfig({
// Uses root-level '.ts' extension
}),
'src/api/schema': defineConfig({
importExtension: '.js', // Overrides root-level for this block
}),
},
};
`

$3

bool (Default: true)

DEPRECATED: Use importExtension instead. This option is kept for backward compatibility.

Determines whether imports emitted should use CommonJS syntax or ESM syntax (with .js file endings)

Config Examples

#### 1. Custom Config

Custom preset config can be set using the presetConfig option:

`yml


codegen.yml


schema: '*/.graphql'
generates:
src/schema:
preset: '@eddeee888/gcg-typescript-resolver-files'
presetConfig:
mode: 'modules'
resolverTypesPath: './types.gen.ts'
typeDefsFilePath: false
typesPluginsConfig: # Pass config you'd normally use for typescript and typescript-resolvers here
nonOptionalTypename: false
federation: true
`

#### 2. Using TypeScript Config File

If you use codegen.ts, you can use the exported defineConfig function to get better TypeScript support:

`ts
import type { CodegenConfig } from '@graphql-codegen/cli';
import { defineConfig } from '@eddeee888/gcg-typescript-resolver-files';

const config: CodegenConfig = {
schema: '**/schema.graphql',
generates: {
'src/schema': defineConfig({
mode: 'modules',
resolverTypesPath: './types.gen.ts',
typeDefsFilePath: false,
typesPluginsConfig: {
// Pass config you'd normally use for typescript and typescript-resolvers here
nonOptionalTypename: false,
federation: true,
},
}),
},
};
export default config;
``