Your First Query with GQFn

Using GQFn feels just like writing native GraphQL queries. This guide assumes you are already familiar with GraphQL query basics.

In this walkthrough, we’ll incrementally build a more complex query step by step.

Preparing the Schema

Before you start writing queries, you need to prepare your schema. Follow the Prepare Schema guide to generate schema types, and use useSchema to obtain the gqfn function. In this example, we’ll use the AniList GraphQL endpoint.

If you haven’t installed gqfn yet, run the following commands:

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

Next, import the gqfn function from the @gqfn/core package and use it to construct your query:

const query = gqfn([])

Selection and Arguments

To select fields on the Query type, simply pass your selection as the argument to the gqfn function.

import { useSchema } from '@gqfn/core'
import { request } from 'graphql-request' // or you favorite GraphQL client

const endpoint = 'https://graphql.anilist.co'
const gqfn = useSchema(endpoint)

Let’s add our first field. Suppose we want the title of the anime with ID 127549. Add the Media field to your selection, and provide the id argument.

Pass arguments as the first parameter to $, and the selection as the second. For example:

GQFn

const query = gqfn([{
  Media: $ => $({ id: 127549 }, [
    'id',
  ]),
}])

const data = await request(endpoint, query)
const id = data.Media?.id // it is typed!

GraphQL

{
  Media {
    id
  }
}

Response

{
  "Media": {
    "id": 127549
  }
}

To get the anime’s title, add the title field to your selection. Since title takes no arguments, you can use the shorthand syntax and pass only the selection.

GQFn provides type hints as you write your query:

const query = gqfn([{
  Media: $ => $({ id: 127549 }, [
    'id',
    {
      title: $ => $([
        '
',
      ]),
    },
  ]),
}])

Since the media is an anime, you can also add the type argument to the selection.

Here’s the complete code. As you can see, the experience closely mirrors writing GraphQL directly:

GQFn

const query = gqfn([{
  Media: $ => $({ id: 127549, type: gqfn.enum('ANIME') }, [
    'id',
    {
      title: $ => $([
        'romaji',
        'english',
        'native',
      ]),
    },
  ]),
}])

const data = await request(endpoint, query)
const id = data.Media?.id
const nativeTitle = data.Media?.title?.native

GraphQL

{
  Media(id: 127549, type: ANIME) {
    id
    title {
      romaji
      english
      native
    }
  }
}

Response

{
  "Media": {
    "id": 127549,
    "title": {
      "romaji": "Slow Loop",
      "english": "Slow Loop",
      "native": "スローループ"
    }
  }
}

Learn more about selection.

Operation Name

The operation name should always be the first argument to the gqfn function.

GQFn

const query = gqfn('query FetchAnime', [{
  Media: $ => $({ id: 127549, type: gqfn.enum('ANIME') }, [
    'id',
    {
      title: $ => $([
        'romaji',
        'english',
        'native',
      ]),
    },
  ]),
}])

const result = await request(endpoint, query)

GraphQL

query FetchAnime {
  Media(id: 127549, type: ANIME) {
    id
    title {
      romaji
      english
      native
    }
  }
}

Response

{
  "Media": {
    "id": 127549,
    "title": {
      "romaji": "Slow Loop",
      "english": "Slow Loop",
      "native": "スローループ"
    }
  }
}

Learn more about operation names.

Variables

Variables let you make your queries dynamic. To use variables, pass the variable definitions as the second argument to gqfn.

Defining and using variables in GQFn is similar to standard GraphQL. Use $ to reference your variables:

GQFn

const query = gqfn('query FetchAnime', {
  id: 'Int!',
}, [{
  Media: $ => $({ id: $.vars.id, type: gqfn.enum('ANIME') }, [
    'id',
    {
      title: $ => $([
        'romaji',
        'english',
        'native',
      ]),
    },
  ]),
}])

const result = await request(endpoint, query, { id: 127549 })

GraphQL

query FetchAnime($id: Int!) {
  Media(id: $id, type: ANIME) {
    id
    title {
      romaji
      english
      native
    }
  }
}

Response

{
  "Media": {
    "id": 127549,
    "title": {
      "romaji": "Slow Loop",
      "english": "Slow Loop",
      "native": "スローループ"
    }
  }
}

You can also set default values for variables:

GQFn

const query = gqfn('query FetchAnime', {
  id: 'Int = 127549',
}, [{
  Media: $ => $({ id: $.vars.id, type: gqfn.enum('ANIME') }, [
    'id',
    {
      title: $ => $([
        'romaji',
        'english',
        'native',
      ]),
    },
  ]),
}])

const result = await request(endpoint, query, {})

GraphQL

query FetchAnime($id: Int = 127549) {
  Media(id: $id, type: ANIME) {
    id
    title {
      romaji
      english
      native
    }
  }
}

Response

{
  "Media": {
    "id": 127549,
    "title": {
      "romaji": "Slow Loop",
      "english": "Slow Loop",
      "native": "スローループ"
    }
  }
}

Learn more about variables.

Learn more about $ and the dollar function.

Going Further

• Directives