Support an incremental adoption of Fragment Masking

[charpeni]

Is your feature request related to a problem? Please describe.

I recently migrated a project to client-preset (from gql-tag-operations-preset) and would like to turn on Fragment Masking for it. Unfortunately, because of existing fragments that are not using Fragment Masking, we already have a thousand errors to handle to be able to.

When you enable Fragment Masking, all fragments, and operations are automatically masked, even though not all fragments or operations use Fragment Masking.

I would like the ability to unmask fragments recursively to support an incremental adoption of Fragment Masking.

Also related to:

• Generate both masked fragment types and full query types. #9308
• Share fragment between query and mutation without masking #9325

Nested Fragment: <UserAvatar>

export const UserAvatarUserFragment = gql(`
  fragment UserAvatarUser on User {
    avatarUrl
  }
`);

type UserAvatarProps = {
  user: ResultOf<typeof UserAvatarUserFragment>;
};

function UserAvatar(props: UserAvatarProps) {
  return <img src={props.user.avatarUrl} />;
}

Fragment: <UserCard>

export const UserCardUserFragment = gql(`
  fragment UserCardUser on User {
    id
    name
    ...UserAvatarUserFragment
  }
`);

type UserCardProps = {
  user: ResultOf<typeof UserCardUserFragment>;
};

function UserCard(props: UserCardProps) {
  return (
    <>
      <UserAvatar user={props.user} />
      {/*         ^ Property 'avatarUrl' is missing in type  */}
      {/*         ^ Type '"UserCardUserFragment"' is not assignable to type '"UserAvatarUserFragment"' */}
      <div>ID: {props.user.id}</div>
      <div>Name: {props.user.name}</div>
    </>
  );
}

Query: <ExampleComponent>

export const ExampleComponentQuery = gql(`
  query ExampleComponent($id: String!) {
    user(id: $id) {
      ...UserCardUser
    }
  }
`);

type ExampleComponentProps = {
  id: VariablesOf<typeof ExampleComponentQuery>['id'];
};

export function ExampleComponent(props: ExampleComponentProps) {
  const { loading, data } = useQuery(ExampleComponentQuery, { variables: { id: props.id } });

  if (loading) {
    return <>loading...</>;
  }

  if (!data?.user) {
    return <>no user</>;
  }

  return <UserCard user={data.user} />;
}

Describe the solution you'd like

We could expose the following utility type: UnmaskResultOf<TypedDocumentNode>.

This would check if whether we're inside an operation or directly within a fragment and then recursively flatten fragments by resolving $fragmentRefs and merging them to the root fragment.

type UserCardProps = {
- user: ResultOf<typeof UserCardUserFragment>;
- // ^? (property) user: { __typename: "User"; id: string; name: string; ' $fragmentRefs': { ... }}
+ user: UnmaskResultOf<typeof UserCardUserFragment>;
+ // ^? (property) user: { __typename: "User"; id: string; name: string; avatarUrl: string }
};

const testUnmaskResultOf: UnmaskResultOf<ExampleComponentQuery> = {
  __typename: 'Query',
  user: {
    __typename: 'User',
    id: 'some-id',
    name: 'some-name',
    avatarUrl: 'some-avatar-url',
  },
};

See the implementation on TypeScript Playground: Link.

Warning: Pull request with the full implementation will follow.

Describe alternatives you've considered

No response

Is your feature request related to a problem? Please describe.

No response

[charpeni]

Here's the implementation: #9380.

[brandonwestcott]

Our team also has the same pain points in our incremental adoption as well.

For others who may need a solution, we ended up generating both masked (src/gql) and fragmentMasking: false (types src/gql/unmasked), and then wrote a couple of helpers to utilize them:

In src/gql/full

import { ResultOf } from '@graphql-typed-document-node/core'
import type { graphql as graphqlUnmasked } from 'gql/unmasked'
import type * as UnmaskedNamespace from 'gql/unmasked/graphql'
import { graphql as graphqlMasked } from './gql'

export const graphql = graphqlMasked as typeof graphqlUnmasked

type Unmasked = typeof UnmaskedNamespace

type GraphqlNodeName = {
  [Key in keyof Unmasked as Key]: (
    Key extends `${infer FragmentName}FragmentDoc` ? FragmentName :
    Key extends `${infer DocumentName}Document` ? DocumentName :
    never
  )
}[keyof Unmasked]

export type FullResultOf<
  Name extends GraphqlNodeName,
  FragmentName = `${Name}FragmentDoc`,
  DocumentName = `${Name}Document`
> = (
    FragmentName extends keyof Unmasked ? ResultOf<Unmasked[FragmentName]> :
    DocumentName extends keyof Unmasked ? ResultOf<Unmasked[DocumentName]> :
    never
  )

Then to fetch the types you can either:
Use the normal types, just importing graphql from gql/full

import { graphql } from 'gql/full'
import { ResultOf } from '@graphql-typed-document-node/core'

const Fragment = graphql(`
  fragment TestFragment_UserFragment on User {
    id
    ...NameCard_UserFragment
  }
`)

type FullUser = ResultOf<typeof Fragment>

Or you can look up the type via its name

import { FullResultOf } from 'gql/full'

const Fragment = graphql(`
  fragment TestFragment_UserFragment on User {
    id
    ...NameCard_UserFragment
  }
`)

type FullUser = FullResultOf<'TestFragment_UserFragment'>

[bryanmylee]

I've built an implementation that takes @charpeni's implementation further, and I've tested for:

1. nested fragments / sibling fragments
2. fragments in nested objects
3. fragments in arrays
4. fragments in optional fields

The implementation can be found here.

[ACERposS]

Just noting that I'm getting a "Type instantiation is excessively deep and possibly infinite" error with @bryanmylee solution above when fragments are deeply nested.

@brandonwestcott solution works in lieu of this, presumably since it generates the types statically.

The remaining quirk is only symptomatic at leafmost nodes of the component tree; passing fragmentized props down until that point should function as intended. Example given with Svelte components:

List element:

<script lang="ts" module>
// ...
const QUERY_FRAGMENT = gql(`
  fragment AllSomethings on Query {
    somethings(filter: $filter) {
      ...ThingFields
    }
  }
`);

export interface Props {
    query: FragmentType<typeof QUERY_FRAGMENT>,
}
</script>

<script lang="ts">
  const { query }: Props = $props();
  const data = useFragment(QUERY_FRAGMENT, query);
</script>

<ul>
  {#if data}
    {@const { somethings } = data}
    {#each somethings as thing}
      <ThingListItem {thing} />
    {/each}
  {/if}
</ul>

List item element:

<script lang="ts" module>
// ...
const ThingFields= gql(`
  fragment ThingFields on Thing {
    id
    name
  }
`);

  export interface Props {
    thing: FragmentType<typeof ThingFields>,
  }
</script>

<script lang="ts">
  const { thing }: Props = $props();
  const data = useFragment(ThingFields, thing);
</script>

<li>
  {#if data}
    {@const record = data as FullResultOf<'ThingFields'>}
    <p>{record.name}</p>
  {/if}
</li>

Note the FullResultOf typecast to the unmasked fragment type is only applied when a component needs to access the record's subfields directly. Prior to that moment TypeScript prefers to pass the fragment masked types around and will error if you pass a FullResultOf<T>.

So.. it's still slightly cumbersome at the edges, but it's close.