graphql-precise-dts

@omnicajs/graphql-precise-dts is a GraphQL Code Generator plugin that generates TypeScript declaration files for GraphQL documents.

The generated declarations:

• keep fragment and operation types scoped to the corresponding .graphql module;
• generate TypedDocumentNode declarations for operations;
• emit a sibling schema.d.ts file with enums and scalar mappings;
• account for directives that can change the runtime response shape;
• support documents that contain multiple fragments, multiple operations, or their combination in the same .graphql file.

Repository status

Current repository layout keeps the plugin implementation and the test generation pipeline separate:

• the plugin implementation lives in src/;
• unit tests live in tests/units;
• type-level tests live in tests/types;
• fixture GraphQL documents live in tests/fixtures/documents;
• test-only generated declarations are written to tests/fixtures/generated.

The repository test suite validates both:

• unit-level behavior of internal modules such as path resolution, renderers, directive handling, planning, and model builders;
• consumer-facing TypeScript behavior against declarations generated by the plugin from test fixtures.

Installation

Install the plugin together with its runtime type dependencies:

yarn add -D @graphql-codegen/cli @omnicajs/graphql-precise-dts
yarn add graphql @graphql-typed-document-node/core

@graphql-typed-document-node/core is required because generated declarations import TypedDocumentNode from that package.

Usage

Example GraphQL Code Generator config:

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

const config: CodegenConfig = {
  schema: 'src/schema.graphql',
  documents: [ 'src/**/*.graphql' ],
  generates: {
    'types/graphql-documents.d.ts': {
      plugins: [ '@omnicajs/graphql-precise-dts' ],
      config: {
        prefix: '~/',
        scope: 'src/',
        relativeToCwd: false,
        scalars: {
          DateTime: 'string',
        },
      },
    },
  },
}

export default config

For this repository itself, fixture declarations used by type tests are generated with:

yarn generate:test-fixtures

Output

For a target like:

types/graphql-documents.d.ts

the plugin produces:

• types/graphql-documents.d.ts with declare module '...' blocks for GraphQL documents;
• types/schema.d.ts with:
  • export type Scalars = ...
  • export type MyEnum = ...

Operation declarations are emitted as typed document exports:

export type GetUserQuery = ...
export type GetUserQueryVariables = Exact<...>
export const getUserQuery: TypedDocumentNode<GetUserQuery, GetUserQueryVariables>
export default getUserQuery

If a single .graphql file contains multiple definitions, the plugin emits all matching fragment and operation declarations into the same declare module '...' block.

If a configured document references a fragment that is missing from the plugin documents input, the plugin emits a warning that names the missing fragment definition and the document that referenced it.

These warnings are diagnostics only. They do not change the generated output or recover external fragment definitions automatically.

Development scripts

yarn lint
yarn lint:fix
yarn test:units
yarn test:types
yarn tests
yarn test:coverage
yarn generate:test-fixtures

yarn tests is the main verification entry point in this repository. It regenerates test fixture declarations and then runs the full Vitest suite with type checks.

__typename behavior

The plugin keeps explicit __typename selections and also synthesizes fallback __typename values when they are needed to describe the response shape precisely.

• for object-like results, fallback __typename is usually optional;
• for Query, Mutation, and Subscription operation results, fallback __typename is optional unless it was selected explicitly;
• for concrete object shapes, selecting __typename through an alias such as kind: __typename suppresses the synthesized fallback __typename; the aliased field is rendered as a regular string-literal field;
• for abstract fields that split into distinct concrete shapes, the plugin may synthesize required discriminating __typename values when no explicit __typename selection exists;
• if __typename is selected only conditionally or only for part of the branches, the generated __typename remains optional;
• if multiple concrete branches collapse to the same rendered shape, the plugin merges them into a single object type and renders __typename as a union of possible string literals.

Reserved name rule:

• aliasing a non-__typename field to the response name __typename is not supported and causes plugin generation to fail.

Configuration

Supported plugin config:

type PluginConfig = {
  prefix?: string
  scope?: string
  relativeToCwd?: boolean
  scalars?: Record<string, string | { input?: string; output?: string }>
  directivePolicies?: Record<string, DirectivePolicy | DirectiveNodePolicies>
}

prefix

Prefix prepended to generated GraphQL module ids.

scope

Optional path prefix used to preserve only the scoped part of the document path in module ids.

relativeToCwd

When enabled, absolute document paths are normalized relative to process.cwd() before generating module ids.

scalars

Overrides scalar TypeScript types.

Examples:

{
  scalars: {
    DateTime: 'string',
  },
}

or:

{
  scalars: {
    DateTime: {
      input: 'string',
      output: 'Date',
    },
  },
}

directivePolicies

Defines how custom directives affect the generated response shape.

Policies can be defined:

• directly for the directive name;
• or per target kind: field, fragmentSpread, inlineFragment.

Supported effects:

• ignore
• exclude
• conditional
• nonnull
• override-type
• warn

Additional documentation

• Module path resolution - path resolution rules and examples for generated declare module ids.
• Directives - built-in directive semantics, custom directive policies, and current __typename behavior for conditional and excluded selections.