useFragment: why use the hook naming convention?

[fromi]

I am trying to apply graphql-code-generator to an existing NextJS project.

I do stuff like that inside the project:
{data?.incomes && data.incomes.map(income => <BoardGameIncome key={income.boardGame.id} income={income}/>)}

Notice how I use a map, and inside the map I use an functional id as the element key.

If I want to keep the same using code generator and fragments, it turns out like this:

{data?.incomes && data.incomes.map(incomeFragment => {
  const income = useFragment(UserIncomeFragment, incomeFragment)
  return <BoardGameIncome key={income.boardGame.id} income={income}/>
})}

If I want to keep my functional id, I need to call "useFragment" inside my map function... It works, however it smells very bad: indeed, useFragment looks like a hook, and hooks cannot be used inside loops in React! Static analysers like ESLint will see an error.
It works because useFragment IS NOT a hook! It a helper function, because it does not call any hook inside.

That made me wondering, why do we need all that "$fragmentRefs" boilerplate inside the generated code?
Why can't we have that:

export type IncomesQuery = { __typename?: 'Query', incomes: Array<(
    { __typename?: 'UserIncome' }
    & UserIncomeDataFragment // instead of: { ' $fragmentRefs': { 'UserIncomeDataFragment': UserIncomeDataFragment } }
  )> };

At least, I think useFragment should be renamed, it is not a hook.

[charlypoly]

Hi @fromi,

I've built the following working example that shows how to make a property usable for React loops:

As you can see here, we request the field used as an iteration key inside and outside of the fragment:
https://github.com/charlypoly/codegen-repros/blob/cffbfd5d8a0d835f8328250858ade371dcfbcc6c/client-preset-fragments-loops/src/App.tsx#L10-L18

it can then be used properly: https://github.com/charlypoly/codegen-repros/blob/master/client-preset-fragments-loops/src/App.tsx#L30

Finally, on your last question regarding $fragmentRefs; those are necessary to provide Fragment Masking capabilities (isolating data dependencies).
You will find more information on this architecture principle on our blog: https://www.the-guild.dev/blog/unleash-the-power-of-fragments-with-graphql-codegen

[pongells]

Woah! I spent hours trying to figure this out. Thanks :)

[fromi]

Thanks for the answer!
Regarding Fragment masking, that's something I do not need on my project so having an option to generate without it would be great :)
And you did not answer the question regarding the naming of "useFragment": is there any reason for it to look like a hook?
Thank you for the great work anyway, I will use that to decouple my back & front in my Next.js project.

[charlypoly]

Regarding Fragment masking, that's something I do not need on my project so having an option to generate without it would be great :)

to disable fragment masking, pass the fragmentMasking: false, option as follow:

const config = {
   schema: '<YOUR_SCHEMA>,
   documents: ['<YOUR_DOCUMENTS>'],
   generates: {
      './src/gql/': {
         preset: 'front-end',
         presetConfig: {
           fragmentMasking: false,
         }
       },
   },
};
export default config;

And you did not answer the question regarding the naming of "useFragment": is there any reason for it to look like a hook?

It is inspired from Relay's convention: useFragment()

[fromi]

Thanks a lot! I had a quick look at the config capability, but I did not find that.