Registry / devops / graphql-code-generator-unmask-fragment

graphql-code-generator-unmask-fragment

library1.2.0jsnpmunverified

A helper library for graphql-code-generator client-preset that provides the `UnmaskFragment` utility type and `makeFragmentData` function to work around the nested fragment masking issue (https://github.com/dotansimha/graphql-code-generator/issues/9702). Version 1.2.0 is current; the package is stable with no frequent releases. It is an interim solution until the upstream PR is merged. Key differentiator: resolves typing problems with nested fragments in client-preset without workarounds.

devops

npm install graphql-code-generator-unmask-fragment

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-CODE-GENER

graphql-code-generator-unmask-fragment

devopsjavascriptv1.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

UnmaskFragment

✓ import { UnmaskFragment } from 'graphql-code-generator-unmask-fragment'

✗ import UnmaskFragment from 'graphql-code-generator-unmask-fragment'

Named export, not default. Use with graphql-code-generator client-preset.

makeFragmentData

✓ import { makeFragmentData } from 'graphql-code-generator-unmask-fragment'

✗ const { makeFragmentData } = require('graphql-code-generator-unmask-fragment')

Named export; CommonJS require also works but ESM is preferred.

FragmentType

✓ import { FragmentType } from 'graphql-code-generator-unmask-fragment'

Re-exported from graphql-code-generator for convenience.

Demonstrates how to use UnmaskFragment to get unmasked types and makeFragmentData to create fragment data for testing.

import { UnmaskFragment, makeFragmentData } from 'graphql-code-generator-unmask-fragment'; import { graphql } from 'gql.tada'; // or from your generated code const UserFragment = graphql(` fragment UserFragment on User { id username } `); const PostWithUserFragment = graphql(` fragment PostWithUserFragment on Post { id body author { ...UserFragment } } `); type User = UnmaskFragment<typeof UserFragment>; // { __typename?: "User" | undefined; id: string; username?: string | null | undefined; } type PostWithUser = UnmaskFragment<typeof PostWithUserFragment>; // Includes nested fragment fields unmasked const testData = makeFragmentData( { id: 'post1', body: 'Hello', author: { id: 'user1', username: 'Alice' } }, PostWithUserFragment ); // testData: FragmentType<typeof PostWithUserFragment>

Debug

Known issues

deprecatedThis package is an interim solution; once the graphql-code-generator PR (#9708) is merged, usage of this package will become obsolete.

fix

Migrate to the built-in unmasking feature from graphql-code-generator when available in a future version.

affects: all

gotchaThe `UnmaskFragment` type works only with fragments defined using the `graphql()` function from `gql.tada` or similar TypedDocumentNode-based generators. Using raw `gql` strings will not produce the correct types.

fix

Ensure fragments are defined using `graphql()` from a library that returns TypedDocumentNode, e.g., `gql.tada` or `@graphql-typed-document-node/core`.

affects: all

gotchaThe `makeFragmentData` function validates data at runtime only loosely; it does not check that the data matches the fragment structure exactly.

fix

Use TypeScript to ensure type safety when constructing data.

affects: all

breakingVersion 1.0.0 requires graphql-code-generator v0.6.0+ and changes the package to ESM-only.

fix

Use `import` syntax instead of `require`. Ensure your project supports ESM.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'graphql-code-generator-unmask-fragment' or its corresponding type declarations.

The package may not be installed or TypeScript cannot resolve it due to missing @types.

fix

Run `npm install graphql-code-generator-unmask-fragment` and ensure tsconfig.json includes "moduleResolution": "node" or "bundler".

Type 'typeof import("...")' is not a valid fragment type.

Using the `UnmaskFragment` type with a fragment defined using `gql` instead of the typed `graphql()` function.

fix

Define fragments using `graphql()` from a TypedDocumentNode library (e.g., `gql.tada`).

Argument of type '{ ... }' is not assignable to parameter of type 'FragmentType<...>'.

Data passed to `makeFragmentData` does not match the expected type of the fragment.

fix

Ensure the data object has the correct shape and all required fields as defined in the fragment.

Cannot use namespace 'UnmaskFragment' as a type.

Using `UnmaskFragment` as both a namespace and type, likely due to import confusion.

fix

Use `import type { UnmaskFragment } from 'graphql-code-generator-unmask-fragment'` for type-only usage.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

@graphql-typed-document-node/corerequiredProvides core types for GraphQL document nodes used by graphql-code-generator

graphqloptionalCore GraphQL library required for TypeScript types

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/tnyo43/graphql-code-generator-unmask-fragment ↗

packagegraphql-code-generator-unmask-fragment ↗

homepagehttps://github.com/tnyo43/graphql-code-generator-unmask-fragment#readme ↗