GQFn

Appearance

First Query with GQFn ​

The experience of using gqfn is very similar to writing plain GraphQL queries. The following content assumes that you already know how to write a GraphQL query.

In this guide, our goal is to gradually build a slightly complex query.

Prepare the Schema ​

Before writing a query, you need to prepare the schema. Follow the guide in Getting Started to generate the schema types. and use useSchema to get the gqfn function. Here we use the endpoint from AniList.

If you haven't install gqfn yet, you can do it by running the following command:

bash
# ✨ Auto-detect package manager
npx nypm install @gqfn/core
npm run gqfn add https://graphql.anilist.co

Then, you can import the gqfn function from @gqfn/core package and use it to create a query.

ts
import {  } from '@gqfn/core'
import {  } from 'graphql-request' // or you favorite GraphQL client
const  = 'https://graphql.anilist.co'
const { , ,  } = ()

Selection and Arguments ​

To build a selection on the Query type, you can pass the selection as the only argument of the gqfn function.

ts
const  = ([])

Ok let's add the first field to the selection. We want to get the title of the Anime with the id 127549. We need to add the Media field to the selection with the id argument.

Pass the arguments as the first argument of the $, and the selection as the second argument. Now we got this:

ts
const  = ([{
  :  => ({ : 127549 }, [
    'id',
  ]),
}])

const  = await (, )
const  = .?. // it is typed!
graphql
{
  Media {
    id
  }
}
json
{
  "Media": {
    "id": 127549
  }
}

But we want to get the title of the Anime. We can add the title field to the selection. We have no need to pass any arguments to the title field so we can use the shorthand syntax, pass the selection as the only argument.

You can get the type hint when writing the query.

ts
const  = ([{
  :  => ({ : 127549 }, [
    'id',
    {
      :  => ([
        '',
      ]),
    },
  ]),
}])

The media we want to get is an anime, so we can also add the type argument to the selection.

The full code is here, you can intuitively see that the writing experience is similar to GraphQL.

ts
const  = ([{
  :  => ({ : 127549, : ('ANIME') }, [
    'id',
    {
      :  => ([
        'romaji',
        'english',
        'native',
      ]),
    },
  ]),
}])

const  = await (, )
const  = .?.
const  = .?.?.
graphql
{
  Media(id: 127549, type: ANIME) {
    id
    title {
      romaji
      english
      native
    }
  }
}
json
{
  "Media": {
    "id": 127549,
    "title": {
      "romaji": "Slow Loop",
      "english": "Slow Loop",
      "native": "スローループ"
    }
  }
}

Learn more about selection.

Operation Name ​

Operation names are useful to make the code less ambiguous. The operation name should be always be the first argument of the gqfn function.

ts
const  = ('query FetchAnime', [{
  :  => ({ : 127549, : ('ANIME') }, [
    'id',
    {
      :  => ([
        'romaji',
        'english',
        'native',
      ]),
    },
  ]),
}])

await (, )
graphql
query FetchAnime {
  Media(id: 127549, type: ANIME) {
    id
    title {
      romaji
      english
      native
    }
  }
}
json
{
  "Media": {
    "id": 127549,
    "title": {
      "romaji": "Slow Loop",
      "english": "Slow Loop",
      "native": "スローループ"
    }
  }
}

Learn more about operation name.

Variables ​

Variables are helpful if we want to query for other anime. You can pass the variables definition as the second argument of the gqfn function.

Writing variables is similar to writing a GraphQL query and you can use the $ to visit you variables.

ts
const  = ('query FetchAnime', {
  : 'Int!',
}, [{
  :  => ({ : ., : ('ANIME') }, [
    'id',
    {
      :  => ([
        'romaji',
        'english',
        'native',
      ]),
    },
  ]),
}])

await (, , { : 127549 })
graphql
query FetchAnime($id: Int!) {
  Media(id: $id, type: ANIME) {
    id
    title {
      romaji
      english
      native
    }
  }
}
json
{
  "Media": {
    "id": 127549,
    "title": {
      "romaji": "Slow Loop",
      "english": "Slow Loop",
      "native": "スローループ"
    }
  }
}

Default values can be set as follows:

ts
const  = ('query FetchAnime', {
  : 'Int = 127549',
}, [{
  :  => ({ : ., : ('ANIME') }, [
    'id',
    {
      :  => ([
        'romaji',
        'english',
        'native',
      ]),
    },
  ]),
}])

await (, , {})
graphql
query FetchAnime($id: Int = 127549) {
  Media(id: $id, type: ANIME) {
    id
    title {
      romaji
      english
      native
    }
  }
}
json
{
  "Media": {
    "id": 127549,
    "title": {
      "romaji": "Slow Loop",
      "english": "Slow Loop",
      "native": "スローループ"
    }
  }
}

Learn more about variables.

Learn more about $ and dollar function.

Going Further ​