Query Functions

Manipule os valores dos campos dentro da query GraphQL, por meio de uma coleção de utilitários e diretivas especiais que fornecem capacidades de meta-programação.

Field to Input

Obtenha o valor de um campo, manipule-o e passe-o como input para outro campo, tudo dentro da mesma query.

query {
  posts {
    excerpt
 
    # Referencing previous field with name "excerpt"
    isEmptyExcerpt: _isEmpty(value: $__excerpt)
 
    # Referencing previous field with alias "isEmptyExcerpt"
    isNotEmptyExcerpt: _not(value: $__isEmptyExcerpt)
  }
}

Iteração e Manipulação de Valores de Campos

Adição de meta-diretivas ao schema GraphQL, para iterar e manipular os elementos de valor de campos array e object:

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem faz com que a diretiva aninhada seja aplicada em um item específico do array.

Na query abaixo, apenas o primeiro item do array com os nomes das categorias é transformado em maiúsculas:

query {
  posts {
    categoryNames
      @underArrayItem(index: 0)
        @strUpperCase
  }
}

...produzindo:

{
  "data": {
    "posts": {
      "categoryNames": [
        "NEWS",
        "sports"
      ]
    }
  }
}

Campo sobre Campo

Adição da diretiva @applyField, para executar um determinado campo sobre o valor do campo resolvido.

Aplicada a algum campo, a diretiva @applyField permite executar outro campo (que está disponível no mesmo tipo e é aplicado no mesmo objeto), e ou passar o valor resultante adiante para outra diretiva, ou sobrescrever o valor do campo.

Na query abaixo, o campo Post.title do objeto tem o valor "Hello world!". Ao adicionar @applyField para executar o campo _strUpperCase:

{
  post(by: { id: 1 }) {
    title
      @passOnwards(as: "input")
      @applyField(
        name: "_strUpperCase"
        arguments: {
          text: $input
        },
        setResultInResponse: true
      )
  }
}

...o valor do campo é transformado em maiúsculas, produzindo:

{
  "data": {
    "post": {
      "title": "HELLO WORLD!"
    }
  }
}

Manipulação Condicional de Campos

Adição das meta-diretivas @if e @unless ao schema GraphQL, para executar condicionalmente uma diretiva aninhada no campo.

@if executa suas diretivas aninhadas somente se uma condição tiver valor true.

Nesta query, os usuários "Leo" e "Peter" têm seus nomes convertidos em maiúsculas, pois estão no array de "usuários especiais", enquanto "Martin" não:

query {
  users {
    name
      @passOnwards(as: "userName")
      @applyField(
        name: "_inArray"
        arguments: {
          value: $userName
          array: ["Leo", "John", "Peter"]
        }
        passOnwardsAs: "isSpecialUser"
      )
      @if(
        condition: $isSpecialUser
      )
        @strUpperCase
  }
}

...produzindo:

{
  "data": {
    "users": [
      {
        "name": "LEO"
      },
      {
        "name": "Martin"
      },
      {
        "name": "PETER"
      }
    ]
  }
}

Valor Padrão de Campo

Adição da diretiva @default, para definir um valor para campos nulos ou vazios.

No exemplo abaixo, quando um post não tem uma imagem destacada, o campo featuredImage retorna null:

{
  post(by: { id: 1 }) {
    featuredImage {
      id
      src
    }
  }
}

{
  "data": {
    "post": {
      "featuredImage": null
    }
  }
}

Usando @default, podemos recuperar uma imagem padrão:

{
  post(by: { id: 1 }) {
    featuredImage @default(value: 55) {
      id
      src
    }
  }
}

{
  "data": {
    "post": {
      "featuredImage": {
        "id": 55,
        "src": "http://mysite.com/wp-content/uploads/my-default-image.webp"
      }
    }
  }
}

Remoção de Campo da Resposta

Adição da diretiva @remove ao schema GraphQL, que remove a saída de um campo da resposta.

Na query abaixo, geramos a URL para enviar uma requisição HTTP concatenando o domínio do site e o endpoint da API REST. Como os valores desses componentes não são de nosso interesse, não há necessidade de exibi-los na resposta, e podemos removê-los com @remove:

query {
  siteURL: optionValue(name: "siteurl")
    @remove
 
  requestURL: _sprintf(
    string: "%s/wp-json/wp/v2/comments/11/?_fields=id,content,date",
    values: [$__siteURL]
  )
    @remove
 
  _sendJSONObjectItemHTTPRequest(
    input: {
      url: $__requestURL
    }
  )
}

...produzindo esta resposta (observe que os campos siteURL e requestURL foram removidos):

{
  "data": {
    "_sendJSONObjectItemHTTPRequest": {
      "id": 11,
      "date": "2020-12-12T04:07:36",
      "content": {
        "rendered": "<p>Btw, I really like this stuff<\/p>\n"
      }
    }
  }
}

Acionador de Erro na Resposta

Adição do campo global _fail e da diretiva @fail ao schema GraphQL, para adicionar explicitamente uma entrada à propriedade errors na resposta, e do campo global _warn e da diretiva @warn, para adicionar uma entrada à propriedade warnings na resposta.

O campo _fail adiciona o erro sempre, e a diretiva @fail sempre que a condição especificada no argumento condition for atendida:

query {
  _fail(message: "Some error")
  
  posts {
    featuredImage @fail(
      condition: IS_NULL,
      message: "The post does not have a featured image"
    ) {
      id
      src
    }
  }
  
  users {
    name @fail(
      condition: IS_EMPTY,
      message: "The retrieved user does not have a name"
    )
  }
}