[client-preset] Fragment masking Q&A

[charlypoly]

Let's discuss all questions related to the client-preset's Fragment Masking.

[charlypoly]

Answers to the initial discussion with @marco2216 on the v3 roadmap (#8296 (comment)):

But what if I want masking enabled in general but just not for fragments that are defined in the same fragment/query string? Maybe it's possible to parse and check that if it's local to the component, don't mask? Or maybe with a special directive or comment?

There is not way to enable Fragment Masking on specific queries or fragments for now.
It can only be enabled/disabled on each output target.

I can cast it to FragmentType<typeof fragmentDocument>, but then I lose the type safety on the data that's passed in. I can type cast an empty object to FragmentType.

I don't see why you would lose type safety here, could you provide an example?

3. If I postfix fragment names with Fragment (like in the docs) the type names don't seem to be deduplicated by default (they will have FragmentFragment as postfix). That caused an issue because I had added dedupeOperationSuffix: true to my config (just copy pasted from prev. config), because the gql.ts file was deduped but not the graphql.ts file. Also when importing the fragment type, if I want to use it somewhere, I would prefer that it's deduped.

The dedupeOperationSuffix: true is not part of the config API option supported by the client-preset.

[ssbb]

Just wondering - if I have some local (to component) helper functions which intended to work with unmasked fragment data type then I still should pass masked fragment and call useFragment in each function?

const MyComponent = (props: { post: FragmentType<typeof PostFragment> }) => {
  const post = useFragment(PostFragment, props.post);

  return (
    <div>
      <h1>{postSummary(post)}</h1>
    </div>
  );
};

const postSummary = (post : ???TYPE???): string => {
  ...
}

Where postSummary generates summary based on data (using ~5 fields). So here I can pass masked data instead and call useFragment in postSummary. Or maybe it's better to just pass this 5 fields manually so postSummary not tied to fragment but to some it's own data?

Also I can just import this data type from generated graphql.ts file but I think it just breaks whole idea of this? 🤔 (or not?)

Sorry, this concept is pretty new to me.

[charlypoly]

Hi @ssbb,

you will need to import the type that corresponds to your fragment, which is named based on the fragment name with a Fragment suffix.
Example:

import { FilmItemFragment } from './gql';

const allFilmsWithVariablesQueryDocument = graphql(/* GraphQL */ `
  query allFilmsWithVariablesQuery($first: Int!) {
    allFilms(first: $first) {
      edges {
        node {
          ...FilmItem
        }
      }
    }
  }
`);

Here, FilmItemFragment would be the proper type to use for your helper function.

[dan-f]

Hi @charlypoly. I've got a question re. testing and re-usability. Let's use the example from the blog post to illustrate:

import { FragmentType, graphql, useFragment } from './gql'
 
const Avatar_UserFragment = graphql(/* GraphQL */ `
  fragment Avatar_UserFragment on User {
    avatarUrl
  }
`)
 
type AvatarProps = {
  user: FragmentType<typeof Avatar_UserFragment>
}
 
export function Avatar(props: AvatarProps) {
  const user = useFragment(Avatar_UserFragment, props.user)
  return <CircleImage src={user.avatarUrl} />
}

Maybe a naive question, but what's the recommended approach for rendering Avatar directly, e.g. in a component test? Ideally one would be able to write something like <Avatar user={{ avatarUrl: '...' }} />. Obviously this can done via casting to any, but is there some utility type to transform FragmentType<typeof Avatar_UserFragment> into { avatarUrl: string }?

[charpeni]

@2snEM6 you'll need to unmask those fragments.

Here's a proposal for it: #9075, and here's the implementation: #9380.

I would suggest copying those utility types into your codebase and testing them with your use cases and providing feedback on them. 🙏

[2snEM6]

Thanks @charpeni

[dan-f]

Hi there @charlypoly, I'm following up on @quangdng's question above. This is a very common scenario for fragments -- they nest. How can we construct a properly typed instance of Test_HowToCreateMe in the following example? If we naively use makeFragmentData, it will have us nesting Test_Foo and Test_Bar data under ' $fragmentRefs'. But this will clearly lead to runtime type errors since the ' $fragmentRefs' property isn't inhabited at runtime.

type Test {
  foo: String!
  bar: String!
  baz: String!
}

fragment Test_Foo on Test {
  foo
}

fragment Test_Bar on Test {
  bar
}

# how can we construct a value of this type?
#
# const howToCreateMe = makeFragmentData({ __typename: 'Test', baz: '...', /* what goes here? */}, Test_HowToCreateMe);
#
fragment Test_HowToCreateMe on Test {
  baz
  ...Test_Foo
  ...Test_Bar
}

For clarity, let's suppose we want to test testMe in the following example, without crashing out or mocking the implementations of foo and bar, meaning it's unacceptable to construct without the sub-fragment values. This is common when e.g. testMe, foo, and bar are react components and we want a rough integration test of how they work together to create UX.

// again, how to construct and properly type the `data` argument here such that `foo` and `bar` get their data dependencies?
function testMe(data: FragmentType<typeof Test_HowToCreateMe>): string {
  const result = getFragmentData(data);
  const baz = result.baz.toUpperCase();
  return `${foo(result)}-${bar(result)}-${baz}`;
}

function foo(data: FragmentType<typeof Test_Foo>): string {
  return getFragmentData(data).foo.toUpperCase();
}

function bar(data: FragmentType<typeof Test_Bar>): string {
  return getFragmentData(data).bar.toUpperCase();
}

It feels like there's a missing API for this at the moment. Hope you can point us in the right direction here.

[vitosamson]

I'm using the following to deeply unmask fragments for use in testing. The UnmaskedDocument type is very similar to @charpeni's but doesn't exhibit the Type instantiation is excessively deep and possibly infinite. typescript errors. The makeFragmentData function is essentially the same as the generated one but uses my UnmaskedDocument type (and also flips the order of the args since that felt more natural to me).

type Primitive = null | undefined | string | number | boolean | symbol | bigint

export type UnmaskedDocument<TQuery> = TQuery extends {' $fragmentRefs'?: infer FragmentRefs}
  ? FragmentRefs extends Record<string, infer FragmentRef>
    ? UnmaskedDocument<FragmentRef & Omit<TQuery, ' $fragmentRefs' | ' $fragmentName'>>
    : never
  : TQuery extends Primitive
  ? TQuery
  : {[key in keyof TQuery]: UnmaskedDocument<TQuery[key]>}

export function makeFragmentData<Fragment extends DocumentTypeDecoration<unknown, unknown>>(
  _fragment: Fragment,
  data: UnmaskedDocument<FragmentType<Fragment>>,
) {
  return data as FragmentType<Fragment>
}

This has been working well for me for a while. If anybody else wants to try it out and confirm it works for you, I'd be happy to open a PR to include that type and updated makeFragmentData in this repo.

[tnyo43]

@vitosamson I was facing the same problem and your solution works for me too. Thank you! I really appreciate if you open a PR and this library adopt this feature.

FYI
I created a small reproduction. customMakeFragmentData is a function that you suggested. I flip the order of the args again just for making them in the same order than the original one (but I agree with your opinion 😌)

https://github.com/tnyo43/make-fragment-test/blob/ff03d6452979dd23e790f577e826e0435ea10a02/src/Profile/index.tsx#L29-L53

[ssbb]

One more Q. I am thinking about performance when passing whole object to render just few fields. Something like this:

const PostTitleFragment = graphql(`
  fragment PostTitleFields on Post {
    title
  }
`);

export function PostTitle(props: { post: FragmentType<typeof PostTitleFragment> }) {
  const { title } = useFragment(PostTitleFragment, props.post);

  return <h1>{title}</h1>;
}

export function Post() {
  // fetch post ...

  return (
    <div>
      <PostTitle post={post} />
    </div>
  );
}

As I know Relay will re-render PostTitle only when title changes. What about this one? It's just nothing more than a type check on TS level so probably when any post title changes it will cause re-render of all components that using it via fragments?

[ssbb]

I mean it def sounds tempting to split a page into section with fragments like this but wondering if there anything I should care about when doing single-field fragments (like on user+avatar example).

[charlypoly]

Hi all,

Please know that a new documentation page, with a dedicated section on Fragment Masking, has been released: https://the-guild.dev/graphql/codegen/plugins/presets/preset-client#fragment-masking

[nandorojo]

As I mentioned at #8603, adding fragment variables would be a big addition. I'm currently unable to use the fragment approach with list components due to this limitation.

[lrholmes]

Is there any pattern or recommendation for supporting multiple possible types passed into a component under a single prop?

Previously I have used ts-pattern + typename to handle this quite elegantly, but can't see an obvious good way to handle the same logic using client-preset types.

Super contrived example (please don't pay too much attention to the specifics around whether the solution is right for this case):

const UserName = graphql(`
  fragment UserName on User {
    __typename
    name
  }
`);
const AdminName = graphql(`
  fragment AdminName on Admin {
    __typename
    firstName
    lastName
  }
`);

// Pre client-preset solution using `ts-pattern`:
export const Name = ({ user: userFragment }: {
  user: UserNameFragment | AdminNameFragment;
}) => match(user)
  .with({ __typename: 'User' }, (typedUser) => typedUser.name)
  .with({ __typename: 'Admin' }, (typedAdmin) => `${admin.firstName} ${admin.lastName}`)
  .exhaustive();

// With client-preset:
export const Name = ({ user: userFragment }: {
  user: FragmentType<typeof UserNameFragment> | FragmentType<typeof AdminNameFragment>; // should that work?
}) =>  {
  // need some way to determine which fragment type was passed  — is that possible right now?
}

Other case where this may be useful is where two fragment's fields match (but are not defined as an interface), and we want to be able to pass either of them into a common component.

[saihaj]

In case like this I usually split my component to Presentational component so I can share the styling. Then I will create a container component which takes one Fragment.

Then the parent passing the fragment you can simply do a switch statement and render based on __typename

[lrholmes]

I have a question regarding useFragment and arrays:

const books = getFragmentData(
  Book,
  order?.books
);

This works, but the returned array is typed as readonly. Why is that? It makes the resulting type difficult to use, and doesn't appear to be necessary. I end up seeing errors like this:

Argument of type 'readonly Book[]' is not assignable to parameter of type 'Book[]'.

As a result, I'm forced to use some other solution, like map:

const books = order?.books.map((bookFragment) => getFragmentData(Book, bookFragment));

Which is okay, but it feels like a bit of a wasteful map considering it's only serving to appease TS.

So yeah, would love to learn why getFragmentData/useFragment types arrays as readonly, or if you'd be open to changing this based on this feedback (to return a regular array).

[KammererTob]

Same issue here. Would also love some clarification what the best practice here is.

[tnyo43]

I have never faced such a problem. Why do you want to use it as a non-readonly array?
If you give us a reproduction, we may be able to find a good practice.

[yuan-93]

I encountered this using tanstack react-table and found a discussion asking react-table to support readonly data TanStack/table#3648

My current workaround is bypass the TS error, since I believe react-table doesn't mutate the data

[socnacom]

Hi,

I would like to know if it is safe to use ResultOf type from @graphql-typed-document-node/core directly instead of using getFragmentData & FragmentType combo for fragment masking ?

Are there any caveat with this way to do ?

Thank you :)

[nandorojo]

i use it sometimes and it works for me

[socnacom]

ok thank you ! I find it's a cleaner approach to use it instead of calling function getFragmentData since it remains static only. Are there notable differences I should be aware of ?

[nandorojo]

the helper function is better to use imo. i would use the ResultOf rarely since it doesn’t combine well with fragment masking.

[eddiew]

I posted a separate question #9748 but figured I'd write here as well. Has anyone else experienced issues with VSCode not picking up fragment definitions from other files?

graphql-codegen itself has no problem generating the correct types, but vs code's graphql plugin can't figure it out

[ikusa]

you need to include the documents that the fragment exist below example for these
.graphqlrc

documents: './src/graphql/**/*.{ts,tsx}'

[eddiew]

Thanks, that was it! I had been using include instead of documents to specify which files it should look at

[marcoslor]

I'm trying to figure it out how to make fragment masking play nice with Jest and Apollo's MockedProvider.
Has anyone use this exact setup before?

I bet fragment masking prevents me from testing my presentational and non presentational components together.

[marcoslor]

I've managed to figure out how to make fragment masking work with Jest and Apollo's MockedProvider for testing both presentational and non-presentational components together (the short example I gave below actually combines them together, but it isn't important). The key is to ensure that the __typename field is included in the mock responses.

Before figuring this out, the "data?.repositories.edges" was always an array of empty objects (even thought there is one repository mocked in the mocks array)

Here's a simplified example:

// Normally this would be in a 
const Repository_Fragment = gql`
  fragment RepositoryFragment on Repository {
    id
    name
  }
`;

const GET_REPOSITORIES = gql`
  query GetRepositories {
    repositories {
      edges {
        node {
          ...RepositoryFragment
        }
      }
    }
  }
  ${Repository_Fragment}
`;

const RepositoryList = () => {
  const { data } = useQuery(GET_REPOSITORIES);

  return (
    <div>
      {data?.repositories.edges.map(edge => (
        <div key={edge.node.id}>{edge.node.name}</div>
      ))}
    </div>
  );
};

const mocks = [
  {
    request: {
      query: GET_REPOSITORIES,
    },
    result: {
      data: {
        repositories: {
          edges: [
            {
              node: {
                __typename: 'Repository', // This is crucial
                id: '1',
                name: 'Repo Name',
              },
            },
          ],
        },
      },
    },
  },
];

it('renders repository information correctly', () => {
  const { findByText } = render(
    <MockedProvider mocks={mocks} addTypename={false}>
      <RepositoryList />
    </MockedProvider>
  );

  expect(findByText('Repo Name')).resolves.toBeInTheDocument();
});

In this example, RepositoryList is a component that uses the GET_REPOSITORIES query, which in turn uses the RepositoryFragment fragment. The mocks array contains the query that you expect your component to make along with the data you want to return for that query. The __typename field in the mock response tells Apollo Client that the object is of type Repository, which allows it to correctly apply the RepositoryFragment fragment.

I hope this helps anyone else who's trying to test Apollo Client code with fragment masking enabled!

[nareshbhatia]

I am trying to figure out how to approach developing with fragments. Assume that we are building a complex component composed with nested components that need fragments. As far as I can tell, I can't start by building the low-level components first because the query does not exist at that level and codegen will not generate any fragments. I have to start top-down, define the highest level component and the nested component tree down to the low-level component for the fragment to be generated. Is this correct? Is there a better way?

[KammererTob]

Yes i think this is correct. Normally i like to approach it from the other direction. Build a large component and then split this up into smaller components with fragments where necessary/suitable.

[nareshbhatia]

Thank you for the confirmation, @KammererTob

[nareshbhatia]

I am trying to use fragments in my code, but for some reason fragments are not being generated.

Here's my highest level component which works perfectly fine. It queries a user object and and displays the user's id & fullName.

const UserProfileDocument = graphql(/* GraphQL */ `
  query UserProfile($id: ID!) {
    user(id: $id) {
      id
      fullName
    }
  }
`);

export default function UserProfile() {
  const { data } = useQuery(UserProfileDocument, {
    variables: {
      id: userId,
    },
  });
  const user = data?.user;
  if (!user) return undefined;

  return (
    <div className="mx-auto max-w-3xl p-4">
      {user.id} {user.fullName}
      <UserProfileHeader />
    </div>
  );
}

Now I want to pull the id & fullName fields into a fragment that will be rendered by the UserProfileHeader component.

Here's my UserProfileHeader component. It defines the UserProfileHeader fragment, but no fragment code is generated. If I uncomment UserProfileHeaderProps, I get an error "const UserProfileHeaderFragment: unknown". What am I missing?

import { graphql, useFragment, FragmentType } from '@/generated/gql';

const UserProfileHeaderFragment = graphql(/* GraphQL */ `
  fragment UserProfileHeader on User {
      id
      fullName
    }
  }
`);

// type UserProfileHeaderProps = {
//   user: FragmentType<typeof UserProfileHeaderFragment>;
// };

export function UserProfileHeader() {
  return <div>UserProfileHeader</div>;
}

[KammererTob]

You need to use the Fragment inside your query i.e. here:

const UserProfileDocument = graphql(/* GraphQL */ `
  query UserProfile($id: ID!) {
    user(id: $id) {
      id
      fullName
      ...UserProfileHeaderFragment
    }
  }
`);

[nareshbhatia]

@KammererTob, in fact the issue was in a different place. There was an extra curly brace in the fragment definition:

const UserProfileHeaderFragment = graphql(/* GraphQL */ `
  fragment UserProfileHeader on User {
      id
      fullName
    }
  }
`);

This completely threw me off. Once I corrected it, the fragment definition started generating and I could move forward.

Would be nice if graphql-codegen could point out syntax errors in fragments (and in GraphQL code in general).

[nareshbhatia]

Here's the completed example if it helps someone: https://github.com/nareshbhatia/graphql-fragments-example-1

[hans-ts]

I have read all the questions here and in the various links you have provided and I am still not sure what masking is for?

Let's say I have a fragment:

fragment UserCore on User {
  id
  name
}

And a query:

query GetUser {
  ...UserCore
  profilePicture
  birthday
}

If I run graphql-codegen the type for GetUser will not include id or name if making is turned on, meaning that my IDE will complain when try to take the results of the query and cast them to type UserCoreFragment. Now, there may be a way to get it to comply with a bunch of extra steps (using FragmentType and useFragment maybe? happy to be educated on this point), but so far that has really not gained me anything.

[dwillett]

I just finished going through the process of converting a code base to client-preset with fragment masking. In my experience, I'd say that the masking is primarily to enforce that the graphql data needs are being colocated properly with the components that need them. Before adopting fragment masking, our colocated fragments were more of a polite suggestion, and there were data leaks everywhere from skirting around it. There was also a lot of reuse of fragments defined elsewhere in other components, just because they happened to require the same data. This led to strange union prop types coupling child components to parents, or scattered Pick<...> or Partial<...> types describing data needs.

Adapting your example:

const PageQuery = gql(`
  query GetUser {
    currentUser {
      ...UserCore
      profilePicture
      birthday
    }
  }
`);

const UserCore = gql(`
  fragment UserCore on User {
    id
    name
  }
`);


function Page() {
  const { data } = useQuery(PageQuery);
  
  if (!data?.currentUser) return null;

  return (
    <>
      <img src={data.currentUser.profilePicture} />
      <UserCore user={data.currentUser} />;
      <span>Birthday: {data.currentUser.birthday} />
    </>
  );
}

function UserCore(props: { user: FragmentType<typeof UserCore> }) {
  const user = useFragment(UserCore, props.user);
  return (
    <>
      <span>id: {user.id}</span>
      <span>name: {user.name}</span>
    </>
  );
}

So the masking above is relevant in both directions to prevent leaking the data needs. The parent will have errors if trying to access id or name directly without unmasking, and the child will get errors attempting to access profilePicture or birthday.

More strictly enforcing the colocated fragments to define the data needs has cleaned up our prop types significantly, and made it clearer which components need what data.

[hans-ts]

Thank you for taking the time to write that! I think I understand what you wrote, but it still just feels like the type safety Typescript already provides, but with more steps. And with the complexity GraphQL already introduces, adding this on top is going to make it difficult for a junior engineer to be productive while having to grok all of this.

I think I have to experiment with it some more to see the light.

[dwillett]

No sweat! I can relate. I think the benefits I'm now seeing from the fragment masking only became evident when I was part-way through migrating and saw how it was transforming the codebase. Also had to talk with colleagues multiple times to hash out what exactly it was doing for us. YMMV, but in our case I think we're better off going forward now.

[nareshbhatia]

Hi folks, I am getting a typescript error with code generated for unions.

My union is defined as follows in the schema:

type OrderEvent {
  id: ID!
  orderEventType: OrderEventType!
  order: Order!
}

type StatementEvent {
  id: ID!
  statementEventType: StatementEventType!
  orders: [Order!]!
}

union Event = OrderEvent | StatementEvent

I am trying to use the OrderEvent in a fragment like this (here's the full code):

import type { FragmentType } from '@/generated/gql';
import { graphql, getFragmentData } from '@/generated/gql';

const OrderAlertItemFragment = graphql(/* GraphQL */ `
  # eslint-disable-next-line @graphql-eslint/no-one-place-fragments
  fragment OrderAlertItem on Alert {
    id
    event {
      ... on OrderEvent {
        id
        orderEventType
        order {
          id
        }
      }
    }
  }
`);

interface OrderAlertItemProps {
  alert: FragmentType<typeof OrderAlertItemFragment>;
}

export function OrderAlertItem(props: OrderAlertItemProps) {
  // eslint-disable-next-line react/destructuring-assignment
  const alert = getFragmentData(OrderAlertItemFragment, props.alert);
  const { event } = alert;
  return (
    <>
      <p className="text-sm font-medium leading-none">{event.orderEventType}</p>
      <p className="text-sm text-muted-foreground">{event.order.id}</p>
    </>
  );
}

However, I am getting typescript errors in the two lines with <p> tags:

Type error: Property 'orderEventType' does not exist on type '{ __typename?: "OrderEvent" | undefined; id: string; orderEventType: OrderEventType; order: { __typename?: "Order" | undefined; id: string; }; } | { __typename?: "StatementEvent" | undefined; }'.
  Property 'orderEventType' does not exist on type '{ __typename?: "StatementEvent" | undefined; }'.

  32 |   return (
  33 |     <>
> 34 |       <p className="text-sm font-medium leading-none">{event.orderEventType}</p>
     |                                                              ^

I don't understand why typescript is looking for property 'orderEventType' on a StatementEvent because the fragment only includes an OrderEvent. Can someone please help?

You can find my full repo here: https://github.com/nareshbhatia/graphql-fragments-example-3

To see the about error, simply build the app as follows:

npm ci
npm run build

[nareshbhatia]

Here's how I solved the issue: instead of creating a fragment on Alert which has the Event union embedded in it, I just created a fragment on OrderEvent.

const OrderEventItemFragment = graphql(/* GraphQL */ `
  # eslint-disable-next-line @graphql-eslint/no-one-place-fragments
  fragment OrderEventItem on OrderEvent {
    id
    orderEventType
    order {
      id
    }
  }
`);

Now in the parent component, I can distribute this OrderEventItem fragment right under OrderEvent:

const alertListDocument = graphql(/* GraphQL */ `
  query alertList {
    alerts {
      id
      event {
        ... on OrderEvent {
          ...OrderEventItem
        }
        ... on StatementEvent {
          ...StatementEventItem
        }
      }
    }
  }
`);

No I am getting the correct types and TypeScript does not complain. Please let me know if this is the right way to go.

Here's the full code.

[nareshbhatia]

Hi folks, I am running into another TypeScript error with union types. Looking for some help to resolve this.

My union looks like this:

union Event = OrderEvent | StatementEvent

Here's my highest level graphql document with two fragments: OrderEventViewFragment & StatementEventViewFragment:

// ----- AlertView.tsx -----
const alertViewDocument = graphql(/* GraphQL */ `
  query alertView($id: ID!) {
    alert(id: $id) {
      id
      event {
        ... on OrderEvent {
          id
        }
        ... on StatementEvent {
          id
        }
      }
      ...OrderEventView
      ...StatementEventView
    }
  }
`);

export function AlertView({ alertId }: AlertViewProps) {
  ...
  const { event } = alert;

  return (
    <div>
      {event.__typename === 'OrderEvent' && <OrderEventView alert={alert} />}
      {event.__typename === 'StatementEvent' && <StatementEventView alert={alert} />}
    </div>
  );
  );
}

Here's how OrderEventViewFragment is defined in the child component. Notice that it has a nested fragment called OrderViewFragment on Order. However, I am getting a TypeScript error when I try to pass the order object down (see error message below). Is there a better way to code this to avoid the TS error?

// ---- OrderEventView.tsx -----
import type { OrderEvent } from '@/generated/gql/graphql';

const OrderEventViewFragment = graphql(/* GraphQL */ `
  fragment OrderEventView on Alert {
    id
    event {
      ... on OrderEvent {
        id
        orderEventType
        order {
          ...OrderView
        }
      }
    }
  }
`);

interface OrderEventViewProps {
  alert: FragmentType<typeof OrderEventViewFragment>;
}

export function OrderEventView({ alert: alertProp }: OrderEventViewProps) {
  const alert = getFragmentData(OrderEventViewFragment, alertProp);
  const { event } = alert;
  const orderEvent = event as OrderEvent;
  const { order, orderEventType } = orderEvent;

  return (
    <div>
      <p>{orderEventType}</p>
      {/**********************************************************************************
        Type 'Order' has no properties in common with type
        '{ ' $fragmentRefs'?: { OrderViewFragment: OrderViewFragment; } | undefined; }'
        ts(2559)
      **********************************************************************************/}
      <OrderView order={order} />  <--- TypeScript error here
    </div>
  );
}

For completeness, here's the definition of the OrderViewFragment in the child component:

const OrderViewFragment = graphql(/* GraphQL */ `
  fragment OrderView on Order {
    id
    account {
      id
      firstName
      lastName
      email
    }
    total
  }
`);

The full code for the application is here, It's the alert-level-fragments branch.

[nareshbhatia]

Hi all, I am trying to figure out how to pass an array fragment to a child component. Didn't find any examples for doing this. Hopefully someone here can help.

My schema:

type Alert {
  id: ID!
  ...
}

type Query {
  alerts: [Alert!]!
}

My parent component that performs the main query is below. Can't figure out how to pass the array down:

const alertsPageDocument = graphql(/* GraphQL */ `
  query alertsPage {
    alerts {
      id
    }
    // ?????? How to do this ??????
    ...AlertList
  }
`);

export function AlertsPage() {
  const { data, loading, error } = useQuery(alertsPageDocument);
  const alerts = data?.alerts;

  return (
    <AlertList alerts={alerts} />
  );
}

My child component that renders the array is below. Can figure out how to accept the array:

const AlertListFragment = graphql(/* GraphQL */ `
  fragment AlertList on Alert[] {  <---- This does not work
    alerts {
      id
      ...
    }
  }
`);

interface AlertListProps {
  alerts: FragmentType<typeof AlertListFragment>;
}

export function AlertList({ alerts: alertsProp }: AlertListProps) {
  const alerts = getFragmentData(AlertListFragment, alertsProp);

  return (
    ...
  );
}

[nareshbhatia]

Hi @dwillett, thanks so much for your help.

I got it to work.

• The query in alertsPageDocument had to be adjusted slightly to match the schema. See here.

const alertsPageDocument = graphql(/* GraphQL */ `
  query alertsPage {
    alertsWithCounts {
      alerts {
        id
        ...AlertList
      }
      counts {
        orderAlerts
        statementAlerts
      }
    }
  }
`);

• Changes to AlertListFragment worked fine, but it started giving typescript errors in the call to sortAndGroupAlerts(). I had to suppress typescript errors and introduce unknown conversion in two places. See here. After that everything started working:

      // @ts-expect-error suppress type error ts(2352) TODO: fix */}
      const groupedAlerts = sortAndGroupAlerts(
        alerts as unknown as AlertSortAndGroupPartial[],
      ) as GroupedAlerts[];
      if (groupedAlerts.length > 0 && groupedAlerts[0].alerts) {
        router.push(`/alerts/${groupedAlerts[0]?.alerts[0].id}`);
      }
    }
  }, [alerts, router, selectedAlertId]);

  // @ts-expect-error suppress type error ts(2352) TODO: fix */}
  const groupedAlerts = sortAndGroupAlerts(
    alerts as unknown as AlertSortAndGroupPartial[],
  ) as GroupedAlerts[];

If there is someway to make typescript happy with these changes, that would be super! Other than that, I am very happy with the solution.

Thanks again.

[nareshbhatia]

@dwillett, the typescript error is indeed due to the readonly array restriction. Agree that it is totally unnecessary! Working out the details.

[nareshbhatia]

Hi @dwillett, I updated my repo to workaround the readonly issue. The last remaining issue is that I have two places where I am grouping and sorting alerts. I need to extract this into a function. So two questions:

1. How do I type the alerts argument in function sortAndGroupAlerts?
2. Is the getFragmentData in AlertList() coded correctly? AlertItemFragment is for one alert & alertsProp is an array of alerts.

const AlertItemFragment = graphql(/* GraphQL */ `
  fragment AlertItem on Alert {
    id
    alertType
  }
`);

// ----- 1. How do I type the alerts argument below? -----
// It takes an array of alerts and returns a grouped and sorted array of alerts
// Adding readonly is totally fine, but couldn't figure out in terms of `AlertItemFragment`
function sortAndGroupAlerts(alerts) {
  const groupedAlerts = groupBy(alerts, (alert) => alert.alertType);
  return PreferredAlertTypeOrder.map((alertType) => ({
    alertType,
    alerts: sortBy(groupedAlerts[alertType], [(alert) => alert.id]),
  })).filter(({ alerts }) => alerts.length > 0);
}

export interface AlertListProps {
  alerts: FragmentType<typeof AlertItemFragment>[];
}

export function AlertList({ alerts: alertsProp }: AlertListProps) {
  // ----- 2. Is this correct? `AlertItemFragment` is for one alert & `alertsProp` is an array of alerts -----
  const alerts = getFragmentData(AlertItemFragment, alertsProp);
  const sortedAlerts = sortAlerts(alerts);
  ...
}

[dwillett]

1. In my experience, utility functions like this that are taking fragment results (and have access to the variable defining the fragment) would use ResultOf from @graphql-typed-document-node/core. If you don't have access to the fragment variable you can alternatively use the code-generated fragment result type itself.

import { ResultOf } from "@graphql-typed-document-node/core";

function sortAndGroupAlerts(alerts: ResultOf<typeof AlertItemFragment>[]) {
   ...
}

2. getFragmentData looks fine the way you've got it. Caveat will be the readonly designation I mentioned, which would require your utility function to be typed readonly. Otherwise you can map to unmask the individual alerts:

const alerts = alertsProp.map(alert => getFragmentData(AlertItemFragment, alert));

[nareshbhatia]

Works like a charm! Thank you so much for your help, @dwillett.

P.S. Yes, needed to add readonly to the argument type. Updated solution here.

[koutaro-masaki]

I really like Fragment Masking. It feels like it lays down clear rails for component design. However, I've noticed a significant flaw in this mechanism.

const UserViewChildFragment = graphql(`
   fragment UserViewChild on User {
     name
   }
 `)
 
 const UserViewChild = ({user}) => {
   const {name} = useFragment(UserViewChildFragment, props.user)
   return <span>{name}</span>
 }
 
 // ---
 
 const UserViewParentFragment = graphql(`
   fragment UserViewParent on User {
     name
     icon
     ...UserViewChild
   }
 `)
 
 const UserViewParent = ({user}) = {
   const {name, icon, ...userViewChild} = useFragment(UserViewParentFragment, user)
   
   return <>
     <span>{name}</span>
     <img src={icon} />
     <UserViewChild user={userViewChild} />
   <>
 }

Code like the one above passes TypeScript checks, but in reality, the name property is extracted from UserViewParent through destructuring, so the user passed to UserViewChild at runtime does not have the name property. To avoid this, it is necessary to establish a rule that either carefully uses or avoids destructuring when child components require fragments. Unfortunately, the very fact that such a rule needs to be established seems to indicate that implementation details are not being effectively concealed. Is there any way to avoid this?

In the current mechanism, passing fragments to child components requires using useFragment, which seems to cause this breakdown. To handle fragments safely, shouldn't there be a type that enforces passing them to child components without using useFragment?

[zeroliu]

I think you need to pass the useFragment result object as-is to UserViewChild.

[koutaro-masaki]

I understand that. My concern is that the generated types do not express that the useFragment result object needs to be passed as-is to UserViewChild. Moreover, the issue is not just that static checking does not catch this error, but rather that it gives the impression that there is nothing wrong at all.

[senritsu]

Unfortunately the current util types and functions have a lot of cases like this, where errors are being masked (pun intended) due to gaps in the types.

[bmulholland]

I'm still pretty lost with the testing approach for fragments with fragment masking, even after reading the docs:

1. They suggest using makeFragmentData but it's not clear what the second argument is. Is it the fragment type imported from the generated files? Is it the fragment itself? There's no import statement in the example, or text specifying, to clarify this.
2. If it's the type imported from the generated files, then it's a type used as a value (second arg), which Typescript complains about.
3. If it's the actual fragment (like, returned value from gql("fragment ...")), then this is a pain to export in Vue, especially when using .vue files. It's possible to do alongside the now-standard <script setup>, but only as a second <script> tag. And when doing so, TS complains that there's an unused fragment in the file, even thought it's used.
4. It appears that makeFragmentData provides negligible value anyway, because it's just doing data as Type. There's no type assertions -- passing in invalid data doesn't get flagged, so there's no guarantees that what we're passing in correct data. It's also misleading: I'd expect that the whole point of using the function is to get type assurances.
5. It therefore appears that the suggested approach of makeFragmentData is no better than {} as ResultOf<GeneratedFragmentType>, but is more complex to do. However, this simpler approach isn't suggested in the docs.
6. It's not clear whether it's not suggested in the docs for a good reason. Should I not be doing this? Why or why not?

In the end I've ended up with something that doesn't throw typescript errors, and is fairly straightforward to use... but isn't officially recommended and little type safety. Getting here took me hours of frustration and feeling lost. I wish it was clearer.

[bmulholland]

Okay, I can't even do THAT because of dotansimha/graphql-typed-document-node#152. So I'm back to just doing as any in my tests... but as I say, unless I'm missing something, it appears that there's actually no difference in trying to type it more specifically.

[bmulholland]

Okay, so the best way to do it, without ResultOf, is actually with makeFragmentData, and exporting the gql fragment, importing that, and using it as the second arg of makeFragmentData. The warning "Unused co-located fragment definition(s)" comes from gql LSP's diagnostic for their approach to fragments, which requires explicitly passing them to their usage (which is clearly better!). It's not needed with this lib; disable the rule with "shouldCheckForColocatedFragments": false in the LSP config.

[senritsu]

Just as a random observation, regarding your point 4, while the implementation does only cast, the typing does in fact provide some value, and prevents some incorrect data from being passed in.

I very deliberately use "some", because during usage in a large-ish codebase we compiled a whole bunch of edge cases where incorrect data does not result in a TS error. makeFragmentData in its current incarnation also completely breaks down with fragments on unions+interfaces, in which case we had no choice but to cast.

[bmulholland]

Yeah that's kinda what I meant about it being misleading. Using it feels like it should be providing assurances that it doesn't keep.