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;
• process directives in two stages:
  • structural policies change whether selections are included, conditional, or forced non-null;
  • generation policies can override rendered field types or emit warnings;
• 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'
import { defineString } from '@omnicajs/graphql-precise-dts'

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: defineString(),
        },
      },
    },
  },
}

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

When repeated or recursive input/output object shapes appear in generated types, the plugin may lift them into named type declarations and render their usage sites as references to those aliases. This keeps recursive structures representable and reduces duplication in the emitted declarations.

Generated export names share the same declaration namespace inside each emitted declare module '...' block. Before rendering a document bundle, the plugin validates that:

• imported enum and fragment type names do not collide with generated fragment exports, operation payload/variables types, or generated aliases;
• generated variable and output aliases are renamed with numeric suffixes such as TreeInput2 when their preferred names are already occupied;
• operation document value exports such as getUserQuery remain unique within the same document bundle.

If two different declarations still resolve to the same exported name after normalization, generation fails with a name-collision diagnostic that identifies both sources.

Collision checks are split by TypeScript namespace:

• type namespace:
  • imported type names;
  • fragment exports;
  • generated variable aliases;
  • generated output aliases;
  • operation ...Variables exports;
  • operation ...Payload exports.
• value namespace:
  • operation document exports such as getUserQuery.

Type exports are validated only against other type exports. Value exports are validated only against other value exports. This matches TypeScript namespace rules for type and const declarations.

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.

If a selection set repeats the same field or fragment spread directly, the plugin emits a warning with source locations for the redundant selections, even when those selections can be merged safely.

These warnings are emitted only for direct repeats within the same selection set level. Repeats that become visible only after flattening inline fragments are still merged in the generated output, but they are not reported as redundant direct repeats.

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

If the same selection set contains repeated selections with the same response name, the plugin tries to merge them using GraphQL-compatible field merging rules. Compatible repeats such as id + id, repeated fragment spreads, or id plus ... on User { id } are deduplicated.

Field selections are merged only when all of the following stay compatible:

• they resolve to the same target field name;
• they use the same field arguments;
• they keep the same nullability and list structure;
• they keep the same override type policy result;
• their nested result value shapes stay compatible.

Repeated fragment spreads are deduplicated only when they target the same fragment type information. Incompatible repeats such as name: nickname + name: id, or the same response name with different field arguments, still fail generation with a conflict diagnostic.

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.
• incompatible selections that resolve to the same response name cause plugin generation to fail with a conflict diagnostic.

Configuration

Supported plugin config:

type PluginConfig = {
  prefix?: string
  scope?: string
  relativeToCwd?: boolean
  scalars?: Record<string, TsType | { input?: TsType; output?: TsType }>
  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.

String-based type config is not supported. Scalar mappings must be declared with TsType helpers. For object literals inside custom type expressions, use defineObject({...}) together with defineObjectField(type, optional?).

Examples:

{
  scalars: {
    DateTime: defineString(),
  },
}

or:

{
  scalars: {
    DateTime: {
      input: defineString(),
      output: defineNamed('Date'),
    },
  },
}

Nullable unions are declared structurally:

{
  scalars: {
    DateTime: {
      output: unionOf(defineNamed('Date'), defineNull()),
    },
  },
}

Object-shaped custom types are declared through keyed field maps:

{
  scalars: {
    JsonObject: defineObject({
      id: defineObjectField(defineString()),
      archived: defineObjectField(defineBoolean(), true),
    }),
  },
}

directivePolicies

Defines how custom directives affect the generated response shape.

At plugin config level, policies can be defined in two forms:

• flat, for all supported target kinds:

{
  directivePolicies: {
    required: { effect: 'nonnull' },
    opaque: { effect: 'override-type', type: defineNamed('OpaqueId') },
  },
}

• or scoped per target kind: field, fragmentSpread, inlineFragment:

{
  directivePolicies: {
    mask: {
      field: { effect: 'conditional' },
      inlineFragment: { effect: 'exclude' },
    },
  },
}

Current pipeline behavior:

• structural effects are ignore, exclude, conditional, nonnull;
• generation effects are ignore, override-type, warn;
• flat policies apply wherever the directive is encountered;
• scoped policies apply only to the matching selection kind;
• if a scoped policy does not define the current selection kind, the directive has no effect for that selection.

Supported effects:

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

Additional documentation

• Module path resolution - path resolution rules and examples for generated declare module ids.
• Types - structural TsType model, available helpers, supported operations, and config examples.
• Directives - built-in directive semantics, custom directive policies, current policy staging, and __typename behavior for conditional and excluded selections.