DEV Community: David Mraz

Using Fetch API For Executing GraphQL Queries And Mutations

David Mraz — Sun, 26 Feb 2023 14:32:51 +0000

Introduction

GraphQL is a powerful tool for querying data from remote servers and my preferred way of building APIs (Application Programming Interface). For some people, it might be difficult to learn as the tutorials are usually written using tools such as Apollo or Relay. These tools are great but often suited for more complicated projects. In certain scenarios, there might be better to choose a more lightweight approach and not increase bundle size with additional libraries. In these cases, you can work directly with the tools available in the browser. In this quick tutorial, we will use fetch, commonly available in your browser. Let’s first quickly revise what fetch is and how it is usually used with REST API, then we can move to simple GraphQL queries execution.

Using Fetch for a simple GET request

Fetch is a modern replacement for older XMLHttpRequest, a tool for sending network requests. It solves a number of problems for fetching data from servers, such as promise chaining. While we will not go into the detail of older XMLHttpRequest in this article, it is important that for historical reasons, you need to count that fetch is not supported in older browsers. If you need to include for example also IE11, you would need to use a polyfill. Check the caniuse page for browser support. In terms of fetch usage outside of the browser, you can use it natively from Node.js 17 as an experimental feature, in earlier versions you can install for example node-fetch library.

The following is an example of a simple request for fetching data allowing you to receive the current Bitcoin price in USD from Yahoo Finance API.

const url = 'https://query1.finance.yahoo.com/v8/finance/chart/BTC-USD';

const options = {
  method: 'GET',
};

fetch(
 url,
 options
)
.then((response) => {
  return response.json();
})
.then((data) => {
  const res = data.chart.result;
  console.info(res);   
  return res;
})
.catch((err) => {
  console.log('err', err)
});

We can see that there are two parameters passed into the fetch function, the URL of the API endpoint and the options parameter, which is for additional configuration, such as the method of the request, headers, Cross-Origin Resource Sharing (CORS) configurations, as well as body for the POST request. The subsequent .then() calls allow us to chain asynchronous promises. In other words, it says that you are first waiting for the result from the API. If it is successful, then we will get the response and convert it using the .json() method. After that, we will wait again on the result of the conversion, where we can finally log the data into the console. For my execution the shortened result is as follows:

{
    "data": {
        "allFilms": {
            "films": [
                {
                    "title": "A New Hope",
                    "releaseDate": "1977-05-25"
                },
                {
                    "title": "The Empire Strikes Back",
                    "releaseDate": "1980-05-17"
                }
            ]
        }
    }
}

You can notice that .catch() method has not been triggered. If everything works properly, only success callbacks are executed, however, if we encounter an error during the request, the error callback will get triggered.

Using Fetch for GraphQL Query

In the previous example, we used the public REST API from Yahoo Finance to execute GET requests for data retrieval. In the second example, we need a GraphQL endpoint for Star Wars API. GraphQL offers the so-called introspection of the schema, which allows us to easily document what data we can retrieve from the server as you can see on the documentation link.

In order to execute the GraphQL query, we need to use the POST method, set content as application/json, and also send GraphQL document stringified in the JSON body. Now, let's move to our example. The GraphQL document attached to the request will look as follows:

query ($first: Int) {
  allFilms(first: $first) {
   films {
    title
    releaseDate
   }
  }
}

Querying is similar to GET requests in REST API and only retrieves data. With GraphQL we need to describe exactly the data that we would like to retrieve. You can see that we have specified to retrieve films with titles and release dates. $first is the so-called variable, this is needed to pass dynamic data to the query and allows us to take just the first n films from the query.

Let’s now move to the exact JavaScript code:

const url = 'https://swapi-graphql.netlify.app/.netlify/functions/index';

const GET_FILMS = `query ($first: Int) {
  allFilms(first: $first) {
   films {
    title
    releaseDate
   }
  }
}`;

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: GET_FILMS,
    variables: {
      first: 2
    }
  })
};

const fetchAPI = async () => {
  try {
    const result = await fetch(
      url,
      options
    );
    const data = await result.json();
    console.info(data);
  } catch (err) {
    console.info(err)
  }
}
await fetchAPI();

We have defined the URL for GraphQL API and our GraphQL document. In this case, we need to specify options as a second argument. As noted above, the option method needs to be set to POST and content should be set to application/json. The body should be stringified JSON with two keys:

query - where we will pass the GraphQL document
variables - which should match the variable definition in the document and schema on the server

You can also note that in the first example with GET request, we have used .thenable() promise chaining, but here we have used async await. Now, when we execute the result, we will obtain the following result:

{
  "data": {
    "allFilms": {
      "films": [
        {
          "title": "A New Hope",
          "releaseDate": "1977-05-25"
        },
        {
          "title": "The Empire Strikes Back",
          "releaseDate": "1980-05-17"
        }
      ]
    }
  }
}

Summary

This is a brief introduction to fetch usage for GraphQL queries, the principle for the mutation will be practically the same as for queries, i.e. passing query and variables. While on complex projects you should strive to use a GraphQL client, such as Apollo, Relay, or others, fetch has an important role, when you need to keep the project size at a minimum. Axios is also a good alternative way to fetch. Be sure to consider browser support when using the fetch. If you like to learn more about GraphQL, e.g. going through the exact structure of the document, queries, mutations, and best practices, be sure to check my free course on GraphQL language.

Text classification with transformers in Tensorflow 2: BERT, XLNet

David Mraz — Tue, 05 May 2020 17:20:19 +0000

Introduction

The transformer-based language models have been showing
promising progress on a number of different natural language processing (NLP)
benchmarks. The combination of transfer learning methods with large-scale
transformer language models is becoming a standard in modern NLP. In this
article, we will make the necessary theoretical introduction to transformer
architecture and text classification problem. Then we will demonstrate the
fine-tuning process of the pre-trained BERT model for text classification in
TensorFlow 2 with Keras API.

Text classification - problem formulation

Classification, in general, is a problem of identifying the category of a new observation. We have dataset $D$ , which contains sequences of text in documents as

D=X_{1}, X_{2},\cdots,X_{N},

where $X_{i}$ can be for example text segment and $N$ is the number of such text
segments in $D$ .

The algorithm that implements classification is called a classifier. The text classification tasks can be divided into different groups based on the nature of the task:

multi-class classification
multi-label classification

Multi-class classification is also known as a single-label problem, e.g. we assign each instance to only one label. Multi in the name means that we deal with at least 3 classes, for 2 classes we can use the term binary classification.
On the other hand, multi-label classification task is more general and allows us to assign multiple labels to each instance, not just one label per example.

Why transformers?

We will not go into much detail on transformer architecture in
this post. However, it is useful to know some of the challenges
in NLP. There are two important concepts in NLP, which are complementary:

Transformers are used to build the language model, where the embeddings can be retrieved as the by-product of pretraining.

Approaches based on RNNs/LSTMs

Most older methods for language modelling are based on RNNs (recurrent neural network). The simple RNNs suffer from the problem known as vanishing gradient problem and therefore fail to model the longer contextual dependencies. They were mostly replaced by the so-called long short-term neural networks (LSTMs), which is also a form of RNN but can capture the longer context in the documents. However, LSTM can process sequences only unidirectional, so the state of the art approaches based on LSTMs evolved into the so-called bidirectional LSTMs, where we can read the context left to right and also right to left. There are very successful models based on LSTMs such as ELMO or ULMFiT and such models are still valid for today's modern NLP.

Approaches based on transformer architecture

One of the main limitations of bidirectional LSTMs is its sequential nature, which makes training in parallel very difficult. The transformer
architecture solves that by completely replacing LSTMs by the so-called attention mechanism (Vashvani et al. 2017). With attention, we are seeing an entire sequence as a whole, therefore it is much easier to train in parallel. We can model the whole document context as well as to use huge datasets to pre-train in an unsupervised way and fine-tune on downstream tasks.

State of the art transformer models

There is a lot of transformer-based language models. The most successful ones are (as of April 2020)

There are slight differences between models. BERT has been considered as the state of the art results on many NLP tasks, but now it looks like it is surpassed by XLNet also from Google. XLNet leverages the permutation language modelling, which trains an autoregressive model on all possible permutation of words in a sentence. For the purpose of illustration, we will use BERT-based model in this article.

BERT

BERT (Bidirectional Encoder Representations from Transformers) (Devlint
et al., 2018) is a method of pretraining language representation. We will not go into much detail, but the main difference from the original transformer (Vaswani et al., 2017) is that BERT does not have a decoder, but stacks 12 encoders in the basic version and increase the number of encoders for bigger pre-trained models. Such architecture is different from GPT-2 from OpenAI, which is autoregressive language model suited for natural language generation (NLG).

Tokenizer

Official BERT language models are pre-trained with WordPiece vocabulary and use, not just token embeddings, but also segment embeddings distinguish between sequences, which are in pairs, e.g. question answering examples. Position embeddings are needed in order to inject positional awareness into BERT model as attention mechanism does not consider positions in the context evaluation.

The important limitation of BERT to be aware of is that the maximum length of the sequence for BERT is 512 tokens. For shorter sequence input than maximum allowed input size, we would need to add pad tokens [PAD]. On the other hand, if the sequence is longer, we need to cut the sequence. This BERT limitation on the maximum length of the sequence is something that you need to be aware of for longer text segments, see for example this GitHub issue for further solutions.

Very important are also the so-called special tokens, e.g. [CLS] token and [SEP] tokens. The [CLS] token will be inserted at the beginning of the sequence, the [SEP] token is at the end. If we deal with sequence pairs we will add additional [SEP] token at the end of the last.

When using transformers library we first load the tokenizer for the model we would like to use. Then we will proceed as follows:

from transformers import BertTokenizer

tokenizer = BertTokenizer.from_pretrained('bert-base-uncased', do_lower_case=True)

max_length_test = 20
test_sentence = 'Test tokenization sentence. Followed by another sentence'

# add special tokens

test_sentence_with_special_tokens = '[CLS]' + test_sentence + '[SEP]'

tokenized = tokenizer.tokenize(test_sentence_with_special_tokens)

print('tokenized', tokenized)

# convert tokens to ids in WordPiece
input_ids = tokenizer.convert_tokens_to_ids(tokenized)

# precalculation of pad length, so that we can reuse it later on
padding_length = max_length_test - len(input_ids)

# map tokens to WordPiece dictionary and add pad token for those text shorter than our max length
input_ids = input_ids + ([0] * padding_length)

# attention should focus just on sequence with non padded tokens
attention_mask = [1] * len(input_ids)

# do not focus attention on padded tokens
attention_mask = attention_mask + ([0] * padding_length)

# token types, needed for example for question answering, for our purpose we will just set 0 as we have just one sequence
token_type_ids = [0] * max_length_test

bert_input = {
    "token_ids": input_ids,
    "token_type_ids": token_type_ids,
    "attention_mask": attention_mask
} print(bert_input)

We can see that the sequence is tokenized, we have added special tokens as well as calculate the number of pad tokens needed in order to have the same length of the sequence as the maximal length 20. Then we have added token types, which are all the same as we do not have sequence pairs. Attention mask will tell the model that we should not focus attention on [PAD] tokens.

tokenized ['[CLS]', 'test', 'token', '##ization', 'sentence', '.', 'followed', 'by', 'another', 'sentence', '[SEP]']
{
  'token_ids': [101, 3231, 19204, 3989, 6251, 1012, 2628, 2011, 2178, 6251, 102, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  'token_type_ids': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 
  'attention_mask': [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0]
}

Now in the practical coding, we will use just encode_plus function, which does all of those steps for us

bert_input = tokenizer.encode_plus(
                        test_sentence,                      
                        add_special_tokens = True, # add [CLS], [SEP]
                        max_length = max_length_test, # max length of the text that can go to BERT
                        pad_to_max_length = True, # add [PAD] tokens
                        return_attention_mask = True, # add attention mask to not focus on pad tokens
              )

print('encoded', bert_input)

The output is the same as our above code.

Pretraining

Pretraining is the first phase of BERT training. It is done in an unsupervised way and consists of two main tasks:

masked language modelling (MLM)
next sentence prediction (NSP)

From a high level, in MLM task we replace a certain number of tokens in a sequence by [MASK] token. We then try to predict the masked tokens. There are some additional rules for MLM, so the description is not completely precise, but feel free to check the original paper (Devlin et al., 2018) for more details.

When choosing the sentence pairs for next sentence prediction we will choose 50% of the time the actual sentence that follows the previous sentence and label it as IsNext. The other 50% we choose the other sentence from the corpus, not related to the previous one and labels it as NotNext.

Both such tasks can be performed on text corpus without labelled examples,
therefore the authors used the datasets such as BooksCorpus (800m words), English Wikipedia (2500m words).

Fine-tuning

Once we have either pre-trained our model by ourself or we have
loaded already pre-trained model, e.g.
BERT-based-uncased, we can start to fine-tune the model on the downstream tasks such as question answering or text classification. We can see that BERT can be applied to many different tasks by adding a task-specific layer on top of pre-trained BERT layer. For text classification, we will just add the simple softmax classifier to the top of BERT.

The pretraining phase takes significant computational power (BERT base: 4 days on 16 TPUs; BERT large 4 days on 64 TPUs), therefore it is very useful to save the pre-trained models and then fine-tune one specific dataset. Unlike pretraining, the fine-tuning does not require much computation power. The fine-tuning process can be done in a couple of hours even on a single GPU. It is recommended to have at least 12GB VRAM in order to fit the batch size into memory. When fine-tuning for text classification we can choose several paths, see the figure below (Sun et al. 2019).

IMDB dataset

We will solve the text classification problem for well-known
IMDB movie review dataset. The dataset consists of 50k reviews with assigned sentiment to each. Only highly polarizing reviews are considered and no more than 30 reviews are included per movie. The following are two samples from the dataset:

Review	Sentiment
One of the other reviewers has mentioned that after watching just 1 Oz episode you'll be hooked. They are right, as this is exactly what happened with me. The first thing that struck me abo...	positive
Petter Mattei's "Love in the Time of Money" is a visually stunning film to watch. Mr. Mattei offers us a vivid portrait about human relations. This is a movie that seems to be telling us what money, p...	negative

The review can be only positive or negative and only one label can be assigned for each review. This leads us to formulate the problem as a binary classification. In addition, we determine the sentiment of each review, therefore we will solve the sub-task of text classification - called sentiment analysis.

When we take a look at the already achieved results, we can see that XLNet, as well as BERT, are the transformer-based machine learning models that achieved best results on IMDB dataset.

Tables	Accuracy
XLNet (Yang et al., 2019)	96.21
BERT_large+ITPT (Sun et al., 2019)	95.79
BERT_base+ITPT (Sun et al., 2019)	95.63
ULMFiT (Howard and Ruder, 2018)	95.4
Block-sparse LSTM (Gray et al., 2017)	94.99

Source: nlpprogress.com

The other two ULMFit (Howard and Ruder, 2018) and Block-sparse LSTM (Gray et al., 2017) are based on LTSMs, not transformer language models. Similar
approaches have great results as well but are slowly replaced for some tasks by transformer language models. BERT and XLNet are consistently in top positions also on other text classification benchmarks like AG
News, Yelp or DBpedia dataset. In this article, we will focus on preparing step by step framework for fine-tuning BERT for text classification (sentiment analysis). This framework and code can be also used for other transformer models with minor changes. We will use the smallest BERT model (bert-based-cased) as an example of the fine-tuning process.

Fine tunning BERT with TensorFlow 2 and Keras API

First, the code can be downloaded on Google Colab as well as on GitHub.

Let's use the TensorFlow dataset API for loading IMDB dataset

import tensorflow_datasets as tfds

(ds_train, ds_test), ds_info = tfds.load('imdb_reviews', 
          split = (tfds.Split.TRAIN, tfds.Split.TEST),
          as_supervised=True,
          with_info=True)

print('info', ds_info)

The dataset info is as follows:

tfds.core.DatasetInfo(
    name='imdb_reviews',
    version=1.0.0,
    description='Large Movie Review Dataset.
This is a dataset for binary sentiment classification containing substantially more data than previous benchmark datasets. We provide a set of 25,000 highly polar movie reviews for training, and 25,000 for testing. There is additional unlabeled data for use as well.',
    homepage='http://ai.stanford.edu/~amaas/data/sentiment/',
    features=FeaturesDict({
        'label': ClassLabel(shape=(), dtype=tf.int64, num_classes=2),
        'text': Text(shape=(), dtype=tf.string),
    }),
    total_num_examples=100000,
    splits={
        'test': 25000,
        'train': 25000,
        'unsupervised': 50000,
    },
    supervised_keys=('text', 'label'),
    citation=InProceedings{maas-EtAl:2011:ACL-HLT2011,
      author    = {Maas, Andrew L.  and  Daly, Raymond E.  and  Pham, Peter T.  and  Huang, Dan  and  Ng, Andrew Y.  and  Potts, Christopher},
      title     = {Learning Word Vectors for Sentiment Analysis},
      booktitle = {Proceedings of the 49th Annual Meeting of the Association for Computational Linguistics: Human Language Technologies},
      month     = {June},
      year      = {2011},
      address   = {Portland, Oregon, USA},
      publisher = {Association for Computational Linguistics},
      pages     = {142--150},
      url       = {http:\/\/www.aclweb.org\/anthology\/P11-1015}
    },
    redistribution_info=,
)

We can see that train and test datasets are split 50:50 and the examples are in the form of (label, text), which can be further validated:

for review, label in tfds.as_numpy(ds_train.take(5)):
    print('review', review.decode()[0:50], label)

<<
review This was an absolutely terrible movie. Don't be lu 0
review I have been known to fall asleep during films, but 0
review Mann photographs the Alberta Rocky Mountains in a  0
review This is the kind of film for a snowy Sunday after 1
review As others have mentioned, all the women that go nu 1

The positive sentiment is represented by 1 and the negative sentiment is represented by 0.

Now we need to apply BERT tokenizer on all the examples. We will map
tokens into WordPiece embeddings. As said, this can be done using encode_plus
function.

# map to the expected input to TFBertForSequenceClassification, see here 
def map_example_to_dict(input_ids, attention_masks, token_type_ids, label):
  return {
      "input_ids": input_ids,
      "token_type_ids": token_type_ids,
      "attention_mask": attention_masks,
  }, label

def encode_examples(ds, limit=-1):

  # prepare list, so that we can build up final TensorFlow dataset from slices.
  input_ids_list = []
  token_type_ids_list = []
  attention_mask_list = []
  label_list = []

  if (limit > 0):
      ds = ds.take(limit)

  for review, label in tfds.as_numpy(ds):

    bert_input = convert_example_to_feature(review.decode())

    input_ids_list.append(bert_input['input_ids'])
    token_type_ids_list.append(bert_input['token_type_ids'])
    attention_mask_list.append(bert_input['attention_mask'])
    label_list.append([label])

  return tf.data.Dataset.from_tensor_slices((input_ids_list, attention_mask_list, token_type_ids_list, label_list)).map(map_example_to_dict)

We can encode the dataset using the following functions:

# train dataset
ds_train_encoded = encode_examples(ds_train).shuffle(10000).batch(batch_size)

# test dataset
ds_test_encoded = encode_examples(ds_test).batch(batch_size)


from transformers import TFBertForSequenceClassification
import tensorflow as tf

# recommended learning rate for Adam 5e-5, 3e-5, 2e-5

learning_rate = 2e-5

# we will do just 1 epoch for illustration, though multiple epochs might be better as long as we will not overfit the model
number_of_epochs = 1


# model initialization
model = TFBertForSequenceClassification.from_pretrained('bert-base-uncased')

# classifier Adam recommended
optimizer = tf.keras.optimizers.Adam(learning_rate=learning_rate, epsilon=1e-08)

# we do not have one-hot vectors, we can use sparce categorical cross entropy and accuracy
loss = tf.keras.losses.SparseCategoricalCrossentropy(from_logits=True)
metric = tf.keras.metrics.SparseCategoricalAccuracy('accuracy')

model.compile(optimizer=optimizer, loss=loss, metrics=[metric])

We have chosen a rather smaller learning rate 2e-5 and only 1 epoch. BERT overfit quite quickly on this dataset, so if we would like to do 2 and more epoch it would be useful to add some additional regularization layers or use for example Adam optimizer with weight decay.

Now we have everything needed in order to start fine-tuning. We will use Keras API model.fit method:

bert_history = model.fit(ds_train_encoded, epochs=number_of_epochs, validation_data=ds_test_encoded)

We have achieved over 93% accuracy on our test dataset.

4167/4167 [==============================] - 4542s 1s/step
- loss: 0.2456 - accuracy: 0.9024
- val_loss: 0.1892 - val_accuracy: 0.9326

That looks reasonable in comparison with the current state of the art results. According to (Sun C et al. 2019) we can achieve up to 95.79 accuracy with BERT large on this task. The only better accuracy than BERT large on this task has XLNet from Google AI Brain. XLNet can be also easily used with transformers library with just minor changes to the code.

Conclusion

We have developed the end to end process to use transformers on the text
classification task. We have achieved great performance with additional ability to improve either by using XLNet or BERT large model. We can also improve accuracy with multi-task fine-tuning, hyperparameter tuning or additional regularization. The process can be adjusted to other NLP tasks with just minor changes to the code.

This article was originally published at https://atheros.ai/blog/text-classification-with-transformers-in-tensorflow-2

Did you like this post? You can clone the repository with the examples and project set-up. Feel free to send any questions about the topic to david@atheros.ai and subscribe to get more knowledge about building AI-driven systems.

How to learn GraphQL, React and Node.js faster

David Mraz — Thu, 20 Feb 2020 15:54:04 +0000

Learning GraphQL, React, Node.js, and engineering, in general, is not easy for most people. In this article, we will go through some of the top cognitive biases that you need to be aware of to accelerate your learning rate, to decide when to switch technologies, and to refactor your code or avoid mistakes that could lead to technical debt and inefficiently spent time. You will avoid going in circles and find that you learn each lesson more quickly.

Introduction

Learning programming and engineering, especially JavaScript, can be tricky. The Node.js ecosystem is changing at a fast pace, leaving your current knowledge outdated. In this fast-paced environment, you need to be aware of how you can accelerate your learning and cut out unnecessary time. As the technology progresses, the important thing is not only to have some specific knowledge about the technology but to adapt thinking patterns to the frequent changes. Thinking patterns and architecture patterns will stay similar and can be applied to different environments and languages. In this article, we will go through the top cognitive biases that are affecting our decisions when we need to refactor or change our tech stack. We will discuss how to avoid bad decisions that keep us from learning faster and suggest tips that will help you increase your learning rate. A lot of these things are also applicable to different domains.

Resistance to changes

I see myself and others to be really attached to their code. A lot of people are working hard on preparing certain architecture, code base or solutions to the problem to only find that the architecture is not modular enough, too error-prone or just does not scale very well. Completely changing or refactoring the architecture is often quite time-consuming and means that a lot of your code will be removed. This is the point where most people will get resistant to change and start rationalizing and finding ways to justify their solution even though logical reasoning wouldn’t support the old solution. In this problem, we are dealing with a number of cognitive biases that affect our decisions. The main biases are:

Commitment bias
Confirmation bias
Post-purchase rationalization

I see that people start new projects with an already predefined technology stack in their head. Their technology stack will match a lot with their current skills. While this is natural, it can lead to accumulating technical debt and to using technology which is not the best fit for the current modern stack. In addition, badly designed architecture leads to dissatisfaction in your team, frustration, and inefficiency. The GraphQL ecosystem is really fast-paced and is still changing a lot. Before each project you need to re-evaluate and adjust your tech stack to reflect the best and most current solutions. This is much harder for projects already in progress. You invest much more time and it becomes more difficult to transition to a more suitable technology. People still tend to go with the old architecture, however, even though in the long term it means that you will choose less modern and efficient solutions and you will spend more time writing state updates, etc. A lot of people resist switching to new technologies even if that new technology would solve many problems in their application as well as saving development time. This is understandable if your codebase is too big to switch, but you should think about gradually refactoring your stack to be up to date with current modern engineering.

Without a doubt you should not adopt new technologies blindly; you need to evaluate each technology separately. Instead of focusing on the time invested in the old code, I would recommend learning from your experience implementing the technology, and recognizing the advantages of adapting different thinking patterns. With these lessons, you will learn how to quickly and efficiently adopt new technologies in the future.

We need to be especially aware of commitment bias as it can lead to the so-called Escalation of commitment. Escalation of commitment is human behaviour pattern where the individual or group will continue the same behaviour rather than alter course, even that decisions are clearly wrong. In certain cases, it can lead to disasters in peoples lives as they are proceeding in the same bad decisions and completely ignore the negative signals. They attached a lot of ego and work to it and the willpower needed to change the decision is increasing with the time. Once you are aware of commitment bias and other similar biases you will make better decisions when it comes to choosing your tech stack. And also that you will also be able to better estimate the right time for significant refactoring and changes to your app. We also need to take into account a number of other biases. The decision to migrate a technology stack is affected by the post-purchase rationalization. This means we place a much higher value on past choices and try to justify these.

Confirmation bias affects these decisions as well. This bias results in people tending to believe things that confirm their beliefs. This can be really dangerous if your beliefs lead to bad decision-making. You will then focus solely on facts that reinforce your beliefs. Let’s take the example of staying with technology that is gradually becoming outdated. You know that you need to switch to new technology or significantly refactor your codebase. But you will stick to finding facts and information that confirm your beliefs and actions. All these biases affect you in a similar way. You are resistant to changing your decisions and being flexible with technologies, and you avoid refactoring and incorporating new things into your codebase.

Focus not only on your strengths but also on those areas you find less enjoyable and more difficult.

You have that bug, that warning in your console that you know that you should have resolved for weeks now. You still prefer to work on new features, things that you know how to resolve, or on a nice frontend feature with great effects that will add a feeling to your website. But the important things that will enable you to grow as the developer also include focusing on those tasks you do not find enjoyable at the moment, but that may bring rewards in the long run. When you resolve that warning, you will get much more insight into how things work at a deeper level. You usually know your libraries just superficially through prepared APIs, but by going after vital but less attractive tasks you will often need to dive into the library codebase. You will learn how other engineers work and what their coding style involves.

Listen to others & get a mentor

Being on a team of people who listen to each other will increase your learning so dramatically that it is invaluable and irreplaceable. You will not just learn the skills of engineering, but also important social skills. If you are a complete beginner it may be difficult to start coding from scratch. You just do not know what you do not know. You will probably make many mistakes in focusing on things that do not matter that much, and it will cost you a lot of time. I would recommend that you join a team with more senior developers so you can ask for help, code reviews, etc. The most common problems in a team environment are that we often encounter a cognitive bias called the IKEA effect that can cause disputes between team members, especially if there are senior developers who have their egos attached to their code. The IKEA effect causes each member to not approach the solution to a problem objectively, and to overvalue their own solution and undervalue those of others. Once you are aware of this issue you can be more logical when you are discussing the best solution for the project with other team members.

Mitigating biases

This is just a small subset of biases good to be aware of when learning programming. The best way to start mitigating the effect biases have on you and your decisions are to be aware of them and start to retrospectively see how they have affected your decisions and behaviour. I would recommend you look at your past behaviour and try to identify some cases in which you were in some sense biased. Try to remember the emotions that you were feeling, be aware of it and start calculating further decisions with that emotion. The key to reducing how much a bias affects you is to disassociate yourself from the feeling itself. Look at the feeling as an external object and evaluate the decisions you made based on real facts. If possible, rely on mathematics and calculating an expected value for each decision. Feelings are a good indicator in some cases but are not entirely accurate. By injecting logic into your learning and work in general you will get much better results and you will be able to focus on key areas and avoid pitfalls and mistakes that lead you to continue working with old legacy tech stacks.

Summary

These are some of the cognitive biases and human tendencies in programming that may hold you back in your progress as an engineer. I would say that it is most important to be flexible in adopting new technologies and not resistant to change while also prioritizing your tasks for long-term success. This will help you to adopt technologies faster, learn more lessons and, indirectly, will also help you increase your learning rate. By adopting new technologies more frequently you will see more codebases and you will “learn to learn” much more effectively. I believe that the ability to learn quickly is the most important skill for success, especially in engineering, as the amount of new technology and complexity of our systems is continually increasing.

Feel free to send any questions or feedback on this article or Atheros blog in general to david@atheros.ai.

GraphQL security in Node.js project

David Mraz — Wed, 19 Feb 2020 16:37:17 +0000

Introduction

GraphQL is a powerful tool, but with great power comes great security risks. One of the biggest advantages of GraphQL is that you are able to get data across multiple resources within a single request. This allows the potential attacker to make complex queries that quickly result in resource exhaustion. In this brief article, we will go through some tips to minimize these risks and secure your GraphQL schema against potential attackers. If you are looking for a starter kit for building secure GraphQL APIs, you can take a look at our company repository for building GraphQL APIs in Node.js.
You can quickly start with the following commands:

git clone git@github.com:atherosai/graphql-gateway-apollo-express.git

install dependencies with

npm i

and start the server in development mode with

npm run dev

Use HTTPS and do not forget about HTTPS redirect

I would not say this issue is GraphQL specific, but nearly all websites should use HTTPS. Moreover, you are communicating with the server in a more secure way. This will also improve your SEO. We often find that some developers forget to add HTTPS redirect or an hts header to your server. Then, if you access http://atheros.ai you will not be redirected to the HTTPS version and then communicate with the using http protocol by accident. If you use express it is also good practice from a security point of view to add helmet middleware to existing server. This library will adjust headers in each request to be more secure. The code for such server can look for example like this:

import express from 'express';
import helmet from 'helmet';
import rateLimit from 'express-rate-limit';
import { PORT, NODE_ENV } from './config/config';
import apolloServer from './initGraphQLServer';
import { httpsRedirect, wwwRedirect } from './lib/http-redirect';

const app = express();

app.enable('trust proxy');
app.use(helmet());

// redirects should be ideally setup in reverse proxy like nignx
if (NODE_ENV === 'production') {
  app.use('/*', httpsRedirect());

  app.get('/*', wwwRedirect());

  app.use(rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100, // limit each IP to 100 requests per windowMs
  }));
}

// GraphQL server setup
apolloServer.applyMiddleware({ app, path: '/graphql' });

app.listen(PORT, () => {
  // eslint-disable-next-line no-console
  console.info(`Express listen at http://localhost:${PORT} `);
});

You can see that we have also added redirect from www to non-www, which is beneficial for SEO. These redirects can be done also, for example, reverse proxy like Nginx.
You might also notice that we limit number of requests with Express middleware for each IP. This is especially important in GraphQL servers.

Resource exhaustion prevention

I think the biggest issue in GraphQL (especially if you want to open the schema to the public) comes with its biggest advantage, and that is the ability to query for various sources with one single request. However, there are certain concerns about this feature. The issue is that potential attackers can easily call complex queries, which may be extremely expensive for your server and network. We can reduce the load on the database a lot by batching and caching with Data Loader. Load on the network, however, can not be reduced easily and has to be restricted. There are various ways to limit the capabilities of the attacker to execute malicious queries. In my opinion, the most important and useful methods are the following:

Rejecting based on query complexity (cost analysis) great for public schema, but needed even for queries behind authorization. A great library for this use case is graphql-cost-analysis as it also provides different cost analysis rules based on the query and not for the whole schema.
Amount limiting restrict the number of objects someone is able to fetch from the database. Instead of fetching every object, it’s better to use cursor-based pagination.
Depth limiting block recursive queries, which are too costly. Usually limiting the amount to depth 7 is good enough.

The following code implementes Apollo server with depth limiting as well as query complexity:

import { ApolloServer } from 'apollo-server-express';
import { GraphQLError } from 'graphql';
import depthLimit from 'graphql-depth-limit';
import queryComplexity, {
  simpleEstimator,
} from 'graphql-query-complexity';
import schema from './schema';
import { NODE_ENV, CUSTOM_ENV } from './config/config';

const queryComplexityRule = queryComplexity({
  maximumComplexity: 1000,
  variables: {},
  // eslint-disable-next-line no-console
  createError: (max: number, actual: number) => new GraphQLError(`Query is too complex: ${actual}. Maximum allowed complexity: ${max}`),
  estimators: [
    simpleEstimator({
      defaultComplexity: 1,
    }),
  ],
});


const apolloServer = new ApolloServer({
  schema,
  introspection: NODE_ENV !== 'production' && CUSTOM_ENV !== 'production',
  validationRules: [depthLimit(7), queryComplexityRule],
  formatError: (err): Error => {
    if (err.message.startsWith('Database Error: ')) {
      return new Error('Internal server error');
    }

    return err;
  },
});

export default apolloServer;

The amount limiting can be for example implemented with custom scalar.

There are many more methods you can implement, but the combination of these three you will cover most cases of malicious queries. None of these methods will solve the problem for every query. Therefore we need to implement a combination of these methods.

Disable introspection

If you are familiar with the tools like GraphQL Playground, you are maybe wondering, how you can know everything about the schema. In GraphQL there is an option to execute the so-called introspection queries of the schema. You can use this tool to know basically everything about the type system of the schema including, what you can query for, available mutations, etc. If you are in a development environment, it is definitely useful to allow introspection for various purposes, In production, however, it can leak important information for potential attackers or it will just reveal information about your new feature, which is not implemented on the fronted. If you want to solve this issue you can use the library called GraphQL Disable Introspection. It allows you to add validation rules that disable introspection. If you are using code above you can pass the options of enabling/disabling introspection in Apollo server. To disable the introspection for everyone is sometimes a bit limited. Therefore it is much better to add introspection on per request bases or to enable introspection only for certain scopes.

Masking errors

When it comes to error handling it is helpful to have a clearly defined method to deal with errors in your GraphQL project. However, it is important to mask every error that users are not allowed to view. For example, if you use an SQL builder such as knex.js, you can then reveal information about your database schema and leak important facts about the project structure to attacker. If you use Apollo server you can define the format error callback like this:

formatError: (err): Error => {
  if (err.message.startsWith('Database Error: ')) {
    return new Error('Internal server error');
  }

  return err;
},

Such callback will mask only database errors to not reveal your schema to potential attackers.

Use npm audit in your CI

One of the biggest security issues in your Node.js project is that you can accidentally use a malicious package or a package with security holes. The danger exists not only for lesser-known npm packages as described in this article, but also for the packages with a large user base. Let’s take the example of the latest incident, which affected the package eslint-scope, which in turn is dependent on some widely used packages like babel-eslint and webpack, see postmortem. In this incident, the credentials of one of the contributors were compromised, and then the new version of the packages with malicious code was published. You will never be able to defend yourself fully if you use some external packages, but you can significantly decrease the risk by using npm audit in your continuous integration pipeline.

Summary

The list definitely does not end here. This is only a small subset of security concerns that you need to consider when deploying your GraphQL app to production. I would suggest to check out our repository, where a lot of security concerns are already addressed. In the project we also use the Eslint Security plugin, which helps you suggest common Node.js security issues.

Did you like this post? You can clone the whole repository with examples from GitHub. Feel free to send any questions about the topic to david@atheros.ai.

GraphQL List - How to use arrays in GraphQL schema (GraphQL Modifiers)

David Mraz — Wed, 12 Feb 2020 16:26:02 +0000

Introduction

It is often common practice in REST APIs to return a JSON response with an array of objects. In GraphQL we would like to follow this pattern as well. In this article we will go through modifiers, a special group of types which allows us to modify the default behaviour of other types. In GraphQL we deal with various groups of types. These groups are as follows:

Scalars and custom scalars
Enums
Objects and input object types
Abstract types - Interfaces and union types
Modifiers

It may be helpful first to go through the articles above. After gaining a fundamental understanding of other types such as scalars and object types you can then move on to modifiers. Next, we can start working on the project set-up so that we can test our queries. We assume that npm, git and Node.js versions higher than 8 are already installed on your computer. Now you can execute this command in your shell

git clone git@github.com:atherosai/graphql-gateway-apollo-express.git

install dependencies with

npm i

and start the server in development with

npm run dev

Then you can move to GraphQL Playground to execute the queries available in this article. In the model project, we use the in-memory database with fake data for executing our queries.

Model schema

Let’s first consider this model schema, which was printed with the printSchema function from graphql-js utilities. The model schema in the repository is built with a class-based approach using the graphql-js library. It is often much clearer to view the whole schema written in Schema definition language (SDL). For some time now, SDL has been a part of the specification and it is often used to build the schema itself using the build schema utility or the library called graphql-tools

"""Input payload for creating user"""
input CreateUserInput {
  username: String!
  email: String
  phone: String
  firstName: String
  lastName: String
  role: UserRoleEnum = ACCOUNTANT
}

"""User type definition"""
type CreateUserPayload {
  user: User!
}

"""User type definition"""
type CreateUsersPayload {
  users: [User]
}

"""An ISO-8601 encoded UTC date string."""
scalar DateTime

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload
  createUsers(input: [CreateUserInput!]!): CreateUsersPayload
}

type Query {
  users(role: UserRoleEnum): [User!]!
}

"""User type definition"""
type User {
  id: ID!
  username: String!
  email: String
  phone: String
  firstName: String
  lastName: String
  role: UserRoleEnum!
  createdAt: DateTime!
  updatedAt: DateTime
}

enum UserRoleEnum {
  ADMIN
  ACCOUNTANT
}

We can see that we have defined one output object type called User with the following fields: id, username, email, phone, firstName, lastName, createdAt, updatedAt. The id field is typed as an ID scalar and other fields are typed as Strings. We’ve also defined the queries user and users. The user query returns the User object based on the passed id. The users query then returns a list of users. We have also defined the non-required enum type role, which is used in the users query as an argument for filtering the result. In this simple schema we used modifiers quite a lot. In the rest of the article, we will go through these use cases.

Modifiers

First, let’s formally define modifier. As we have already mentioned, modifier is a special group of types in GraphQL. These types can be defined as follows:

A Modifier modifies the type to which it refers.

From this definition, it is clear that we always need to define the type to which we are applying the modifier. In current GraphQL specification, we have these two types of modifiers. Each of the modifiers is classified as a separate type:

List
Non-Null

The List modifier will be our main focus in this article. It will allow us to define if we would like to return a sequence of types. A Non-Null modifier allows us to define if the type/field is required. This can be null (default behavior in GraphQL) or is required and the GraphQL server raises an error. In this article, we will focus mainly on List modifiers and leave a more in-depth discussion of Non-Null modifiers for another article.

List

In general, a GraphQL list represents a sequence of values. It is possible to view these values as arrays (e.g. in Javascript), although the analogy is not completely precise. As we mentioned a list keeps items in an order. In SDL the list modifier is written as square brackets with the wrapped instance of the type in the bracket. In our schema, we used the list modifier to define that if we call the query users, it returns a sequence of types of User from the database. This is achieved by defining the schema as follows:

type Query {
  user(id: ID!): User
  users(role: RoleEnum): [User!]!
}

By calling query users we expect to return a list of users. Let’s see how this looks when we use the graphql-js library. The queries in our repository are defined as follows:

import {
  GraphQLList,
  GraphQLNonNull,
} from 'graphql';
import { getUsers } from '../../operations/users-operations';
import User from './UserType';
import UserRoleEnum from './UserRoleEnumType';

const UserQueries = {
  users: {
    type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(User))),
    args: {
      role: {
        type: UserRoleEnum,
      },
    },
    resolve: (_source, { role }) => {
      const result = getUsers();
      if (role != null) {
        return result.filter((user) => user.role === role);
      }
      return result;
    },
  },
};

export default UserQueries;

We can see that we achieve the same functionality as with SDL. The GraphQLList class represents the List. We have applied the instance of this class to the instance of User. Now we are able to fetch the data by executing the users query in GraphQL Playground with the Play button.

We should retrieve this data and obtain users as a list.

{
  "data": {
    "users": [
      {
        "id": "7b838108-3720-4c50-9de3-a7cc04af24f5",
        "firstName": "Berniece",
        "lastName": "Kris",
        "username": "Ana_Quigley"
      },
      {
        "id": "66c9b0fd-7df6-4e2a-80c2-0e4f8cdd89b1",
        "firstName": "Bradly",
        "lastName": "Lind",
        "username": "Winona_Kulas12"
      },
      {
        "id": "718590a1-33ac-4e61-9fef-b06916acd76b",
        "firstName": "Leila",
        "lastName": "Schowalter",
        "username": "Isabell.Kautzer"
      },
      {
        "id": "411df0f3-bb2c-4f5f-870f-3db9c30d754f",
        "firstName": "Laila",
        "lastName": "Breitenberg",
        "username": "Christophe.Oberbrunner"
      },
      {
        "id": "e1254480-d205-4be8-abfa-67ad7dcd03fb",
        "firstName": "Joe",
        "lastName": "Crist",
        "username": "Dahlia.Gerhold56"
      },
      {
        "id": "d0087200-9621-4787-a3db-cebbede163e6",
        "firstName": "Bettye",
        "lastName": "Bartoletti",
        "username": "Thad_Mayert"
      }
    ]
  }
}

The other use case for List modifiers is for designing the createUsers mutation, where we can add users in batch. There are multiple reasons to design the mutations in this way. We may need to add users in a transaction, therefore we cannot have a different resolver context or we just want to simplify the API or improve the performance and execute the mutation for multiple users more quickly. This is a great use case for applying the List modifier to our input payload. We can define the input object type just once like this:

import {
  GraphQLString,
  GraphQLInputObjectType,
  GraphQLNonNull,
} from 'graphql';
import UserRole from './UserRoleEnumType';

const CreateUserInputType = new GraphQLInputObjectType({
  name: 'CreateUserInput',
  description: 'Input payload for creating user',
  fields: () => ({
    username: {
      type: new GraphQLNonNull(GraphQLString),
    },
    email: {
      type: GraphQLString,
    },
    phone: {
      type: GraphQLString,
    },
    firstName: {
      type: GraphQLString,
    },
    lastName: {
      type: GraphQLString,
    },
    role: {
      type: UserRole,
      defaultValue: UserRole.getValue('ACCOUNTANT').value,
    },
  }),
});

export default CreateUserInputType;

or in SDL language

input CreateUserInput {
  username: String!
  email: String
  phone: String
  firstName: String
  lastName: String
}

and then apply List modifier to achieve the ability to pass multiple payloads in one input variable.


import {
  GraphQLList,
  GraphQLNonNull,
} from 'graphql';
import { isEmail } from 'validator';
import { createUser, createUsers } from '../../operations/users-operations';
import CreateUserInput from './CreateUserInputType';
import CreateUserPayload from './CreateUserPayload';
import CreateUsersPayload from './CreateUsersPayload';

const UserMutations = {
  createUser: {
    type: CreateUserPayload,
    args: {
      input: {
        type: new GraphQLNonNull(CreateUserInput),
      },
    },
    resolve: (_source, args) => {
      const { input } = args;

      if (input.email && !isEmail(input.email)) {
        throw new Error('Email is not in valid format');
      }
      return {
        user: createUser(input),
      };
    },
  },
  createUsers: {
    type: CreateUsersPayload,
    args: {
      input: {
        type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(CreateUserInput))),
      },
    },
    resolve: (_source, { input }) => {
      const createdUsers = createUsers(input);
      return {
        users: createdUsers,
      };
    },
  },
};

export default UserMutations;

We can execute the mutation with using inline arguments or if you prefer with using variables

mutation {
  createUsers(input: [{lastName: "Test", firstName: "test", username: "t1est"}, {lastName: "Test", firstName: "test", username: "te2st"}]) {
    users {
        id
        firstName
        lastName
        phone
        email
        username
    }
  }
}

Now let’s go through the rules for result and input coercion. If you are not familiar with these terms, you can take a look at the article on scalars, where we describe input and result in coercion.

Result coercion

For the query users, result coercion is relevant for us as we would like to obtain an array of users from the executed query. When we coerce lists, the GraphQL server needs to ensure that the returned data from the resolver function will remain in the same order. The coercion of each item in the list is then delegated to the result coercion of the referenced type; each item of the array needs to comply to User type or null value. If it returns an object instead of array-like in this resolver function:

import {
  GraphQLList,
  GraphQLNonNull,
} from 'graphql';
import { getUsers } from '../../operations/users-operations';
import User from './UserType';
import UserRoleEnum from './UserRoleEnumType';

const UserQueries = {
  users: {
    type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(User))),
    args: {
      role: {
        type: UserRoleEnum,
      },
    },
    resolve: (_source, { role }) => {
      const result = getUsers();
      if (role != null) {
        return result.filter((user) => user.role === role);
      }
      return result;
    },
  },
};

export default UserQueries;

the GraphQL server should then raise this error

Expected Iterable, but did not find one for field Query.users.

This happens if the coercion of the List modifier does not comply But what happens if some of the items in the list do not coerce properly? In that case, we handle the error in a similar manner. We return null instead of the value returned from the resolver function and add an error to the response.

Input coercion

When discussing input coercion of List modifiers we can take into account the createUsers mutation and describe the behavior that raises an error. In contrast to the result coercion, where some items from the result array can be obtained even if one item is not coerced properly, in input coercion we will not be able to execute the whole mutation if one payload cannot be coerced. Let’s take a look at the following example, where we would like to pass a list of two payloads, but one payload does not comply with the input type and does not have the required username field. Upon executing this mutation we receive the following error:

Argument "input" has invalid value [{username: "testtest", email: "test@test.com", firstName: "test", lastName: "test"}, {email: "test@test.com", firstName: "test", lastName: "test"}].
In element #1: In field "username": Expected "String!", found null.

The whole mutation fails even if only the input coercion in the input object type in one item in the list does not comply. However, it is important to emphasize that if we pass null as follows, the whole mutation will be executed. However, this depends on whether or not we applied any additional modifiers and composed the modifiers in a more complex type. We will go through this topic in the last section of this article on Modifier composition.

Modifier composition

If we consider the definition of the modifier above, we know that the modifier basically creates a new type from the referenced type with additional functionality. In our case, we are adding behavior so that the result coercion will accept a list of items and not just the item itself. This is also similar to higher-order functions or the decorator pattern and in the same manner, we can chain higher-order functions or HOCs in React. We are also able to compose modifiers by applying a modifier to the type where the previous modifier is already applied. We can combine the Non-Null modifier with our List modifier in the following way. This way we basically combine three modifiers, which are chained as follows

new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(User)))

This creates a special type. When using only a list modifier we are allowed to return a null value from the resolver. We can even combine the items in the array to contain null values as in this array:

mutation {
  createUsers(input: [{username: "testtest", email: "test@test.com", firstName: "test", lastName: "test"}, null]) {
    id
    username
    firstName
  }
}

But when we apply the composed modifier as above, we are only allowed to pass the array containing the objects that comply with the User type. The list above will, therefore, be rejected. The null value returned from the resolver will be also rejected. You can take a look at the table below, which contains what each modifier will allow in order to get a better idea of which combinations of modifiers are suitable for different use cases. The only rule in chaining modifiers applies to Non-null modifiers. It declares that we cannot wrap one Non-Null modifier with another Non-Null modifier.

[User]	[UserObject, null]	Valid
[User]	null	Valid
[User]	[null]	Valid
[User]	[UserObject]	Valid
[User!]	[UserObject,null]	Invalid
[User!]	[null]	Invalid
[User!]	null	Valid
[User!]	[UserObject]	Valid
[User!]!	[UserObject, null]	Invalid
[User!]!	null	Invalid
[User!]!	[UserObject]	Valid
User!!	-	Invalid

UserObject in this table can be equal for example to

{ lastName: "Test", firstName: "test", username: "t1est"}

For simplicity, we did not cover the differences between input and output coercion for these more complex types. The behavior is different only as we discussed in the result and input coercion section. If there would be different UserObject, which do not comply with User type coercion (e.g. does not have username property), there would be additional rules.

Summary

In this article, we have covered one special group of types in GraphQL called Modifiers. With modifiers, we are allowed to inject special behavior into the referenced GraphQL type, add a List and other required fields, and even combine these use cases to build more complex types. Modifiers are a great tool to make elegant GraphQL schemas.

Did you like this post? You can clone the whole repository with examples. Feel
free to send any questions about the topic to david@atheros.ai.

Input object type as an argument for GraphQL mutations and queries

David Mraz — Mon, 03 Feb 2020 14:28:01 +0000

Introduction

In the previous article, we talked about the basic set-up for GraphQL projects as well as the use of GraphiQL for executing queries and mutations. With this knowledge, we can now dive deeper into the world of GraphQL input types. GraphQL is a query language, which can be used with different languages like Javascript, C#, Scala, and more. However, in this article we will focus on Facebook's Javascript implementation of GraphQL called graphql-js. We will also introduce some code snippets and examples illustrating how different types can be written in the GraphQL schema language. This is not language-specific, however, and the main focus will be on designing a GraphQL schema using the graphql-js classes. We will concentrate on the often misunderstood topic of using GraphQL input object types in mutations.

Input and output types

According to GraphQL specification, when we deal with its type system, we have to discuss two different categories of types:

output type can be used for definition of data, which is obtained after query execution;
input types are used as a query parameters, e.g., payload for creating a user. In graphql-js library we basically have two different types, which can be used as objects. GraphQLObjectType (an output type), and GraphQLInputObjectType (an input type).

Designing our mutation

Now let's consider creating a schema for saving users into a database. We will not use a real database, as it is not the main focus of our article. The in memory database is good enough for us to get started. For more information, please check out this repository on my GitHub account, where the in-memory database is implemented. You can quickly start with this command

git clone git@github.com:atherosai/graphql-gateway-apollo-express.git

The types in the schema have some additional fields than in the following examples, but it still illustrates all the concepts precisely. We can start building a schema by defining the data structure. In GraphQL this means defining our GraphQL types, which we can do using the GraphQLObjectType from the graphql-js library. By defining the GraphQLObjectType and also a corresponding query or mutation, we can then query for desired fields to retrieve from the database. When we query a field in GraphQL, we are basically asking for a unit of data. Each field can be a scalar type or an enum type. A field is also sometimes called a leaf, a name from graph theory related to tree graphs.
To create a new instance of GraphQLObjectType in graphql-js we have to use at least some of these parameters:

name* - Each name of an object type has to be unique across the schema;
fields* - Fields can be an object with field definitions or a function, which returns an object with field definitions. Each field must have a type definition, and the other optional attributes are description and default values. An object has to have at least one field;
description - This is an optional attribute, but is really useful for GraphQL schema documentation.

Now let's try to create a simple User Object with the following fields: id, username, email, phone, role, firstName, lastName and two timestamps createdAt and updatedAt.

import {
  GraphQLString,
  GraphQLID,
  GraphQLObjectType,
  GraphQLNonNull,
} from 'graphql';

const User = new GraphQLObjectType({
  name: 'User',
  description: 'User type definition',
  fields: () => ({
      id: {
          type: new GraphQLNonNull(GraphQLID),
      },
      username: {
          type: new GraphQLNonNull(GraphQLString),
      },
      email: {
          type: GraphQLString,
      },
      phone: {
          type: GraphQLString,
      },
      firstName: {
          type: GraphQLString,
      },
      lastName: {
          type: GraphQLString,
      },
  }),
});

export default User;

It can be also written in SDL


"""User type definition"""
type User {
  id: ID!
  username: String!
  email: String
  phone: String
  firstName: String
  lastName: String
}

Both ways of defining our type offer their own advantages and disadvantages. However, If you want to use the Schema Definition Language for more complex schema, it is better to use some third party tool like graphql-tools. More information can be found, for example, in Apollo docs or in some of other articles. Now let’s consider designing a mutation for adding users. If you do not use Relay, the query string for executing this mutation may look like this:

mutation {
  createUser(email: "david@atheros.ai", firstName: "David", lastName: "Mráz", phone: "123456789", username: "a7v8x") {
    user {
      id
      username
      firstName
      lastName
      email
      phone
    }
  }
}

The parameters passed into a createUser() are called arguments. All the fields we are asking for is then called selection set. An argument, for example, could be a scalar argument like GraphQLString or also GraphQLInputObjectType from the graphql-js library. The mutation above can be written in our schema in the following way:

import {
  GraphQLList,
  GraphQLNonNull
} from 'graphql';
import { isEmail } from 'validator';
import { createUser } from '../../operations/users-operations';
import CreateUserPayload from "./CreateUserPayload";

const UserMutations = {
  createUser: {
      type: CreateUserPayload,
      args: {
          username: {
            type: new GraphQLNonNull(GraphQLString),
          },
          email: {
            type: GraphQLString,
          },
          phone: {
            type: GraphQLString,
          },
          firstName: {
            type: GraphQLString,
          },
          lastName: {
            type: GraphQLString,
          },
      },
      resolve: async ({}, { input }) => {
          if (input.email && !isEmail(input.email)) {
              throw new Error('Email is not in valid format');
          }
          return createUser(input);
      },
  },
}

export default UserMutations;

We can see that we do not want to pass the id, as the server generates an id for every new user. In resolver, we have added a simple email validation function for new user emails using a library called validator js. The email validation can be also done by defining the custom scalar type. For simplicity’s sake, we’ll leave that to another article. As for the mutation arguments, if you do not use some static type checking like Flow, this can lead to different errors, as a lot of arguments have to be specified. For these reasons, it is not considered a good practice. This problem can be solved with the so-called parameter object pattern. The solution is to replace a lot of arguments with an input object and then we can only reference the input object and access its properties with dot notation. This pattern is enforced in Relay by default. It is commonly considered a best practice to use an object, called input, as an argument for the specific mutation. I would recommend not only using it in Relay, but also in Apollo or just any other schema that does not us a GraphQL client. The need for the use of this pattern increases with the number of arguments. However, it is good to follow this practice in every mutation.

Applying parameter object pattern on our mutation

Now let’s apply parameter object pattern on our createUser mutation. First, we need to define the UserInput, which can be used as a parameter object for the mutation. This code accomplishes this goal

import {
  GraphQLString,
  GraphQLInputObjectType,
  GraphQLNonNull,
} from 'graphql';

const CreateUserInputType = new GraphQLInputObjectType({
  name: 'CreateUserInput',
  description: 'Input payload for creating user',
  fields: () => ({
    username: {
      type: new GraphQLNonNull(GraphQLString),
    },
    email: {
      type: GraphQLString,
    },
    phone: {
      type: GraphQLString,
    },
    firstName: {
      type: GraphQLString,
    },
    lastName: {
      type: GraphQLString,
    },
  }),
});

export default CreateUserInputType;

or again in SDL:

input CreateUserInput {
  username: String!
  email: String
  phone: String
  firstName: String
  lastName: String
}

You may ask yourself, why do I need to have two different types of input and output? Isn’t it possible to just use GraphQLObjectType on both arguments and field definitions? The reason is that GraphQL needs two different structures. One is for taking input values and coercing them into server-side values, and the other is responsible for fetching data from a server. If we have these two types together, the type has to implement both of these structures. This problem is also discussed in GraphQL specification

The Object type defined above is inappropriate for re‐use here because Objects can contain fields that express circular references or references to interfaces and unions, neither of which is appropriate for use as an input argument. For this reason, input objects have a separate type in the system.

Another difference is also, that GraphQLNonNull, basically responsible for not allowing null values in the query, has a different meaning. When it comes to GraphQLObjectType, if we query for the field in the object, the return value from the resolver function has to do two things. It needs to contain the field with the correct attribute, and it cannot be equal to null. As for input types, we need to specify the field, wrapped by a GraphQLNonNull instance, even just to execute the mutation. You can also check out this thread. Nevertheless, it is possible to avoid the boilerplate, which occurs if you define the fields twice. In my projects, I often assign the fields, used in both GraphQLObjectType and GraphQLInputObjectType, to a specific object. These fields are then imported into each type using the object spread operator. However, you have to be able to avoid circular dependencies and other issues, which come up when designing a more complex schema using graphql-js. Now we have defined the GraphQLInputObjectType, so it is possible to replace our previous mutation with the following code

import {
  GraphQLList,
  GraphQLNonNull
} from 'graphql';
import { isEmail } from 'validator';
import { createUser } from '../../operations/users-operations';
import CreateUserInput from "./CreateUserInputType";
import CreateUserPayload from "./CreateUserPayload";

const UserMutations = {
  createUser: {
      type: CreateUserPayload,
      args: {
          input: {
              type: new GraphQLNonNull(CreateUserInput),
          },
      },
      resolve: async ({}, { input }) => {
          if (input.email && !isEmail(input.email)) {
              throw new Error('Email is not in valid format');
          }
          return createUser(input);
      },
  },
}

export default UserMutations;

We can observe some reduction in complexity. This does not have such a high impact if we just use GraphiQL for executing the mutation:

mutation createUser {
  createUser(input: {
      username: "test", 
      email: "test@test.cz", 
      phone: "479332973", 
      firstName: "David", 
      lastName: "Test"
    }) {
    user {
        id
        username
        email
        phone
        firstName
        lastName
    }
  }
}

However, in a real app we often use variables instead. When we pass the mutation variable input using some frontend GraphQL caching client like Apollo, Relay, or even with some promise based HTTP client like Axios, we can then benefit from reducing costly string building. We pass variables separately from the query document and also reduce the code significantly. If we do not have an input object, the query with variables looks like this:

mutation createUser($email: String, $firstName: String, $lastName: String, $phone: String, $username: String!) {
  createUser(email: $email, firstName: $firstName, lastName: $lastName, phone: $phone, username: $username) {
    user {
      id
      firstName
      lastName
      phone
      email
      username
    }
  }
}

Nevertheless, by rewriting the mutation with the parameter object pattern we can then write it in the following format and significantly simplify our code:

mutation createUser($input: UserInput!) {
  createUser(input: $input) {
    user {
      id
      firstName
      lastName
      phone
      email
      username
    }
  }
}

There is a big advantage of designing a mutation like this. We can reduce the complexity of the frontend code and follow best practices in our project. The importance of input types increases with the number of arguments we have in a mutation. However, we should use best practices even if the mutation payload has just one argument.

Did you like this post? You can clone the repository with examples and project setup.
Feel free to send any questions about the topic to david@atheros.ai.

GraphQL best practices for GraphQL schema design

David Mraz — Tue, 28 Jan 2020 13:52:52 +0000

This article is a part of free GraphQL Language course. To fully understand the content you need to be familiar with basic GraphQL concepts like SDL language, GraphQL document syntax or GraphQL object types and scalars. If you do not have this knowledge, you can take a look at our older articles on our older articles on atheros.ai and on our medium publication.

Introduction

In this article, we will go through various ways and basic patterns to help design schema in the best possible way. This is definitely not a complete guide; this is just a shortlist of best practices and instructions on how to avoid the biggest pitfalls that regularly come up. For more advanced info on designing your GraphQL schemas check out our free GraphQL language course. It is useful to approach schema design by making a check-list of what your schema should provide to guide you through the design process.

Using input object type for mutations

It is extremely important to use just one variable for your mutations and use the input object type to simplify the structure of your GraphQL documents. In our schema, the example is our createPlanet mutation. In SDL this is written as follows:

type Planet implements Node {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime
  name: String
  description: String
  planetType: PlanetTypeEnum
}
input CreatePlanetInput {
  name: String!
  galaxyId: ID!
  description: String
}
type Mutation {
  createPlanet(input: CreatePlanetInput!): Planet!
}

We can see that we only have one argument input - this is typed as an input object type. We are applying a non-null modifier to ensure that the input payload cannot be null. To get more details on this pattern including why we should use it and how to implement it, you can follow this article on input object types and this one on GraphQL lists and Non Null modifiers.

Returning affected objects as a result of mutations

When working with mutations it is considered good design to return mutated records as a result of the mutation. This allows us to update the state on the frontend accordingly and keep things consistent. To illustrate the concept let’s look at the following mutation:

type Mutation {
  createPlanet(input: CreatePlanetInput!): Planet!
  updatePlanet(input: UpdatePlanetInput!): Planet!
}

We can see that we return Planet! as a result of this mutation. This is then used by the cache and we can use it to update the store. In the createPlanet mutation we append the object to the list of planets. This normally needs to be done in the code. In the second example for updatePlanet, however, we can update the Planet automatically by its id.

Using paginated lists by default

Paginated results are really important for security reasons and for ability to limit amount of records we would like to retrieve from the server. It is a good practice to structure paginated results as follows:

type PageInfo {
  endCursor: String
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
}
type ConstellationConnection {
  nodes: [Constellation]
  pageInfo: PageInfo!
  totalCount: Int!
}

This pagination is based on the so-called cursor based pagination. Whenever you fetch lists, I suggest you use paginated lists by default. You will avoid breaking changes of the schema in the future and it is almost always a much more scalable solution. You can also easily implement amount limiting and protect yourself against resource exhaustion attacks, where someone can query an overwhelming number of records from your database at once.

Nesting your objects in queries

When building GraphQL schemas I often see faulty patterns which affect caching and hinder the efficiency of GraphQL queries on the client. If we rewrite our planet type with this bad practice we would write something like this:

type Planet implements Node {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime
  name: String
  description: String
  planetType: PlanetTypeEnum
  galaxyId: ID!
}

The problem here is the galaxyId. For the cache on the frontend, there will be inconsistencies. You need to think about the schema, reuse the types, and substitute these ids with the proper type. If you want to query for the planet’s constellation you need to do two queries. First, call the planet with the galaxyId, and then pass the galaxyId to an additional query. This is really inconvenient and does not maximize the power of GraphQL. In GraphQL it is much better to nest the output types. This way we can call everything with one single request and also perform caching and batching with data loader.

type Planet implements Node {
  id: ID!
  createdAt: DateTime!
  updatedAt: DateTime
  name: String
  description: String
  planetType: PlanetTypeEnum
  galaxy: Galaxy!
}

When we query for the planet and we want to include its constellation we can just call this GraphQL query:

query getPlanets {
  planets {
    nodes {
      id
      name
      constellation {
        id
        name
        createdAt
      }
    }
  }
}

Elevating schema design with interfaces

The interfaces and unions are powerful tools for abstracting different concepts, reducing complexity and simplifying our schema. The best example for interfaces is the Node Interface. The Node interface is enforced by Relay.js, but I would recommend implementing it to other schemas as well. Even if they do not use Relay.js on the frontend, it will still help to reduce complexity. To gain a more in-depth understanding of interfaces you can check out this article or our GraphQL language course.

Think about future schema changes

When implementing your initial schema, try to think about all possible future changes. In general, just invest in the schema. Think about where you can expect to add additional fields in the future and add output object types and input object types there so that you will not have to introduce breaking changes later on. If you are building a more complex app, just do not use GraphQL schema generators blindly. GraphQL schema generators are definitely useful in certain cases like prototyping or for instant high-performance APIs from the database, but in general, I would suggest to think about the schema design and tailor it to your frontend needs.

Use consistent naming in your schema

It's really important to keep naming conventions consistent not just in GraphQL schema design. It is common good practice to use camelCase for your fields and pascalCase for the names of types. I find also useful to name for example input types like this:

(action)(type)Input

(action) is Create, Update or Delete and (type) is the name of the type or entity, which is being updated. Although it is important to not get caught in designing schema in just simple crud operations, but tailor mutations to your frontend needs. We also need to ensure that some common patterns like pagination are named in the same manner. We use the PageInfo type and connection for the paginated list with nodes. Another good practice for enums is to use all capital letters for ENUM values, as they are basically constants.

I hope that you liked this shortlist of best practices for GraphQL schema design. Feel free to ask any question and feedback at david@atheros.ai.

Generate Javascript static types from GraphQL: TypeScript and Flow

David Mraz — Mon, 20 Jan 2020 09:12:17 +0000

Introduction

Javascript is usually considered as an untyped or weakly-typed language. I will not go into the discussion about this topic in this article. You can check out for example this StackOverflow thread for more information. We currently cannot prove the correlation between using statically/dynamically typed languages and number of defects in the system, but there are some evidences that errors occur less when using statically typed language. You can go more deeply into the topic in the following study. In addition statically typed languages can offer smart tooling integrated in your IDE, which enables you to perform more complex autocompletion and linting. Javascript is one of the most widely spread and demanding language. You can use it for frontend, backend or even mobile development. Javascript has definitely a lot of advantages, but as it is untyped it does not support static typings by default. Fortunately, we can enhance the Javascript language using the following tools to add static typings to our project:

TypeScript
Flow

Flow is open-sourced by Facebook and we are able to perform type checking with a Flow server while coding. On the other hand, TypeScript is maintained by Microsoft. TypeScript is older then Flow and seems to me that the ecosystem is much better. TypeScript has better support with typings for more libraries, especially on the backend. In this article we will use solely TypeScript in our examples.

Model example of manual static typing for GraphQL queries

Let’s first take a look at how to define our static typings manually. We will start with this simple schema:

type Subscription {
  id: ID!
  email: String!
}

input SubscribeInput {
  email: String!
}

type Mutation {
  subscribe(input: SubscribeInput!): Subscription!
}

type Query {
  subscriptions: [Subscription]
}

We would like to fetch the list of subscribed users. If you have your development server running you can move to GraphQL Playground. We can then execute the following GraphQL document:

query getSubscriptions {
  subscriptions {
    id
    email
  }
}

Now if you use our example repository. Let's say we would like to include generate our TypeScript types each time we change our GraphQL schema and propagate these changes to your development workflow, so that you can use it directly in your frontend components
We can execute this query in GraphiQL and we will receive something like this

{
  "data": {
    "subscriptions": [
      {
        "id": "02b7d240-0d44-11ea-bbff-1b2383f1b30b",
        "email": "david@atheros.ai"
      }
    ]
  }
}

Then we will start writing our TypeScript type definitions. We will first need to manually check the schema so that our definitions are in sync with the data from the GraphQL server. We can write the definition for Subscriptions query as follows:

export interface Subscribe {
  id: string;
  email: string;
}

export interface GetSubscriptions {
  subscriptions: Subscribe[];
}

We need to manually check our schema to see what each type represents so that our static typings are in sync. Let’s say we want to add the required field source that will be typed as a enum value. The updated Subscription type in SDL (Schema Definition Language) will then be as follows:

enum SourceEnum {
  ARTICLE
  HOME_PAGE
}

type Subscription {
  id: ID!
  email: String!
  source: SourceEnum!
}

In order to fetch this field we will need to update our GraphQL query as well:

query getSubscriptions {
  subscriptions {
    id
    email
    source
  }
}

But what about our typings? We need to update the affected typings wherever they are being used. I believe that the biggest trade off for static typing is the increased time for development, the duplication of data structure and the possible friction that can occur with versioning our APIs. We cannot only update our code; we also need to add our typings manually and then update them after each change. It can lead to wrong typings and false errors if developers do not sync up immediately. These problems can be solved with automatic generation of types with GraphQL. Our GraphQL gateway will serve as our single source of truth, and static typing will be synced immediately on both the frontend and backend.

How would we achieve that with GraphQL?

So now that we have talked about adding typings in our TypeScript code manually, how can GraphQL help us automate that? As we mentioned, one of the biggest problems when defining typings is that the manual static typing can get too time-consuming and it is hard to keep everything in sync through versioning. We could already notice the connection between GraphQL type system and either the TypeScript or Flow type systems. GraphQL’s type system is strongly typed, and we can perform transformations from GraphQL type system to TypeScript type systems.

To get a better idea of how this works in practice let’s visualize how to transform the GraphQL types into TypeScript types. First let’s take a look at this graph

We will first define our GraphQL schema on our server. Then we need to generate static typings on the frontend to type the results and arguments for queries and mutations. We also need to generate separate static typings on the backend for our resolvers. Every time our GraphQL schema changes we also need to update our affected static typings. The GraphQL gateway is now the single source of truth for typings, but in order to remove the friction between definitions we need to introduce automation. This way we will not have to keep everything in sync manually.

Generating types on the frontend with GraphQL CodeGen

Let’s generate TypeScript types for our responses from the GraphQL server. We will use a library called GraphQL CodeGen.

We will use our example repository.
In order to execute the code you can clone the repository with

git clone git@github.com:atherosai/next-react-graphql-apollo-hooks.git

install dependencies with

npm i

and start the server in development with

npm run dev

GraphQL CodeGen yaml file

GraphQLCodeGen works on modular bases. There is a lot of plug-ins that enables you apply GraphQL CodeGen library to many different applications. For now we will use just two plug-ins

TypeScript operations plugin: enables to generate types for mutations and queries
TypeScript plugin: generate basic types from the schema

schema: 'server/schema/typeDefs.ts'
documents: 'components/**/*.graphql'
generates:
  generated/typescript-operations.ts:
    - typescript-operations
    - typescript

We can see that we need to first define a way how to retrieve the information about the schema. This is done in the schema field and in our case we used typeDef file, where schema in SDL is written. GraphQLCodeGen will then apply schema introspection and uses the results to generate TypeScript types.
If your GraphQL server is running on port 3000, you can also perform introspection directly on the endpoint. Please note that for security purposes you should disable introspection in production; it should therefore only work in a development environment.
We have also defined our path to GraphQL documents. In the example repository we store our GraphQL queries and mutations at our React component and the pattern above will validate all of them against our GraphQL schema and then generate TypeScript types for frontend. The last lines in the our GraphQLCodeGen config defines output path of the generated types and plug-ins used.

If you have installed graphql-codegen globally and you are in the folder of our example repository you can just execute:

graphql-codegen

otherwise you can use our npm script command:

npm run gen:schema

This command will run a schema introspection query, take every *.graphql file that matches the specified pattern and validate it with our GraphQL schema. Based on each GraphQL file we will generate a new TypeScript types.

TypeScript output and how to use it in your React components

GraphQLCodeGen generated .ts, .d.ts files with types for each **.graphql* requests into generated folder and we are able to import them into our React-Apollo components. Please note that for the sake of simplicity we did not implement React components in the repository. If you would like to generate Flow types or other supported types you can only change --target parameter. The following TypeScript file for the getUsers query should now be available in the queries/generated

export type Maybe<T> = T | null;
export type SubscribeMutationVariables = {
  input: SubscribeInput
};


export type SubscribeMutation = (
  { __typename?: 'Mutation' }
  & { subscribe: (
    { __typename?: 'Subscription' }
    & Pick<Subscription, 'id' | 'email' | 'source'>
  ) }
);

export type SubscriptionsQueryVariables = {};


export type SubscriptionsQuery = (
  { __typename?: 'Query' }
  & { subscriptions: Maybe<Array<Maybe<(
    { __typename?: 'Subscription' }
    & Pick<Subscription, 'id' | 'email' | 'source'>
  )>>> }
);

/** All built-in and custom scalars, mapped to their actual values */
export type Scalars = {
  ID: string,
  String: string,
  Boolean: boolean,
  Int: number,
  Float: number,
};

export type Mutation = {
   __typename?: 'Mutation',
  subscribe: Subscription,
};


export type MutationSubscribeArgs = {
  input: SubscribeInput
};

export type Query = {
   __typename?: 'Query',
  subscriptions?: Maybe<Array<Maybe<Subscription>>>,
};

export enum SourceEnum {
  Article = 'ARTICLE',
  HomePage = 'HOME_PAGE'
}

export type SubscribeInput = {
  email: Scalars['String'],
  source: SourceEnum,
};

export type Subscription = {
   __typename?: 'Subscription',
  id: Scalars['ID'],
  email: Scalars['String'],
  source: SourceEnum,
};

I believe that the best way to operate is to generate type definitions every time you change your GraphQL schema. This will make your types up-to-date and you will avoid mismatches on your frontend. Now let's use our generated types for our React components in the repository.
In our project we have one query for fetching subscriptions

query getSubscriptions {
  subscriptions {
    id
    email
    source
  }
}

On the client we are rendering our results in the table with two columns email and source. We use Apollo client and React Hooks for our data fetching. React component is written as follows:

import React from 'react';
import get from 'lodash.get';
import uuid from 'uuid/v1';
import { useQuery } from '@apollo/react-hooks';
import SUBSCRIPTIONS_QUERY from './SUBSCRIPTIONS.graphql';
import { SubscriptionsQuery, SubscriptionsQueryVariables } from '../../../__generated__/typescript-operations';
import s from './SubscriptionsTable.scss';

const SubscriptionsTable: React.FunctionComponent = () => {
  const { data, loading, error } = useQuery<SubscriptionsQuery,
  SubscriptionsQueryVariables>(SUBSCRIPTIONS_QUERY);

  if (loading) return <>Loading...</>;
  if (error) return <>{`Error! ${error.message}`}</>;

  return (
    <div className={s.SubscriptionTable}>
      <table>
        <thead>
          <tr>
            <th>Email</th>
            <th>Source</th>
          </tr>
        </thead>
        <tbody>
          {data && data.subscriptions && data.subscriptions.map((subscription) => (
            <tr key={get(subscription, 'id', uuid())}>
              <td>
                {get(subscription, 'email')}
              </td>
              <td>
                {get(subscription, 'source')}
              </td>
            </tr>
          ))}
        </tbody>
      </table>

    </div>
  );
};

export default SubscriptionsTable;

Apollo client is written in TypeScript so it has good support for handling your types. We are passing our generated types in the useQuery hook.
Our second GraphQL operation is subscribe mutation. Our component is written as follows:

/* eslint-disable jsx-a11y/label-has-for */
import React from 'react';
import { useMutation } from '@apollo/react-hooks';
import {
  Formik, ErrorMessage, Form, Field,
} from 'formik';
import * as Yup from 'yup';
// eslint-disable-next-line import/no-extraneous-dependencies
import { FetchResult } from 'apollo-link';
import get from 'lodash.get';
import s from './Subscription.scss';
import SUSCRIBE_MUTATION from './SUBSCRIBE.graphql';
import SUBSCRIPTIONS_QUERY from '../SubscriptionsTable/SUBSCRIPTIONS.graphql';
import { SubscribeMutation, SubscribeMutationVariables, Query } from '../../../__generated__/typescript-operations';

interface InitialValuesI {
  email: string;
}
interface HandleSubscribeI {
  values: InitialValuesI;
  subscribeMutation: Function;
  resetForm: Function;
}


const handleSubsribe: Function = async ({
  values,
  subscribeMutation,
  resetForm,
}: HandleSubscribeI) => {
  const subscribeResult: Promise<SubscribeMutation> = await subscribeMutation({
    variables: {
      input: {
        source: 'HOME_PAGE',
        ...values,
      },
    },
  });

  if (get(subscribeResult, 'data.subscribe')) {
    resetForm();
  }

  return subscribeResult;
};


const Subscription: React.FunctionComponent = () => {
  const [subscribeMutation] = useMutation<SubscribeMutation, SubscribeMutationVariables>(
    SUSCRIBE_MUTATION,
    {
      update: (cache, { data }: FetchResult): void => {
        const dataResult = cache.readQuery<Query>({ query: SUBSCRIPTIONS_QUERY });
        cache.writeQuery({
          query: SUBSCRIPTIONS_QUERY,
          data: {
            subscriptions: dataResult
            && dataResult.subscriptions
            && dataResult.subscriptions.concat([data && data.subscribe]),
          },
        });
      },
    },
  );
  const initialValues: InitialValuesI = {
    email: '',
  };
  return (
    <div className={s.Subscription}>
      <div className={s.Subscription__SubscriptionWrapper}>
        <div>
          <h2>
            Lorem ipsum is place-holder text commonly used in the graphic, print, and publishing
            industries for previewing layouts and visual mock-ups.
          </h2>
          <Formik
            initialValues={initialValues}
            onSubmit={async (values, { resetForm }): Promise<SubscribeMutation> => handleSubsribe({
              values,
              subscribeMutation,
              resetForm,
            })}
            validationSchema={Yup.object().shape({
              email: Yup.string()
                .email()
                .required('Before submitting you need to provide your email'),
            })}
          >
            <Form>
              <div className={s.Subscription__Row}>
                <label htmlFor="email">Email</label>
                <Field
                  id="email"
                  className={s.Carousel__EmailInput}
                  name="email"
                  placeholder="your@email.com"
                  type="email"
                />
                <button type="submit" className={s.Subscription__SubscribeButton}>
                    Subscribe
                </button>
              </div>
              <div className={s.Subscription__FieldErrorRow}>
                <ErrorMessage
                  name="email"
                  component="div"
                  className={s.Subscription__FieldError}
                />
              </div>
            </Form>
          </Formik>
        </div>
      </div>
    </div>
  );
};

export default Subscription;

In this case we used useMutation hook and again passed our generated types into useMutation function. These steps enabled us to use generated types on the client and each time we will change our GraphQL schema we will get up to date TypeScript suggestions.

Generating typed-safe resolvers on your server with GraphQLCodeGen

In order to generate server-side typings for your resolvers we need to use additional plugin. After updating our codegen.yaml we will get the following:

schema: 'server/schema/typeDefs.ts'
documents: 'components/**/*.graphql'
generates:
  __generated__/typescript-operations.ts:
    - typescript-operations
    - typescript
  server/__generated__/resolver-types.ts: 
    - typescript
    - typescript-resolvers

We can generate our types again with:

npm run gen:schema

Now we have generated also types for our resolvers to server/generated/resolver-types.ts. We can now type all of our resolvers as follows:

import { getSubscriptions, createSubscription } from '../requests/subscription-requests';
import { Resolvers } from '../__generated__/resolver-types';


interface StringIndexSignatureInterface {
  [index: string]: any;
}

type StringIndexed<T> = T & StringIndexSignatureInterface

const resolvers: StringIndexed<Resolvers> = {
  Query: {
    subscriptions: () => getSubscriptions(),
  },
  Mutation: {
    subscribe: async (__, args) => createSubscription({}, args),
  },
};

export default resolvers;

How to take it even further?

But what about not just generating static types? What about generating your own code? This is something the GraphQLCodeGen library can also accomplish with plug-ins. For our project the most relevant plugin is for React Apollo.
This can help you to skip one additional manual step of creating React Apollo components for mutations and queries.

Summary

I believe that automatic type and code generation is one of the biggest trends in GraphQL ecosystem. We are having great ecosystem for development especially for TypeScript and GraphQLCodeGen. You can use our starter project to speed up your set-up. This will help you diminish unnecessary friction between your static typing on the frontend with the GraphQL API. You can inject the command to regenerate types after each change in your GraphQL schema files. This way you will have your types automatically in sync with your API. A further advantage is that no extra communication between backend and frontend team members is required, since frontend engineers are notified about the changes in their types. We are additionally able to validate your queries and mutations in CI to avoid deploying queries and mutations on the frontend that do not comply to the current GraphQL schema. There is definitely space for improvement in libraries, especially for server side typings, but current implementations using GraphQLCodeGen is a promising step for more efficient work-flows. I believe that automatic type generation of static types using GraphQL not only in TypeScript has a bright future. It will allow us to spend less time writing boilerplate code and updating our types and more time on shipping high-quality typed products.

Originally published at https://atheros.ai/blog/generate-javascript-static-types-from-graphql-typescript-and-flow

Did you like this post? You can clone the repository with the examples and project set-up.
Feel free to send any questions about the topic to hello@atheros.ai.

Top AI and Machine Learning Books for Business Leaders In 2020

David Mraz — Thu, 16 Jan 2020 17:46:21 +0000

Introduction

AI & machine learning are becoming part of today's products more than ever before. It is now even more important for businesses to have a clear vision of how artificial intelligence intersects with their mission. This is the reading list we recommend to our partners to get insights into the current ecosystem. It is important to say that while this list is completely relevant for 2020, it does not mean that all books were published recently. For example, Singularity Is Near was published in 2005, but it is increasingly relevant today.

Life 3.0 - Being Human In The Age Of Artificial Intelligence

Max Tegmark is a physicist and cosmologist and author of some well-known cosmological books like Our Mathematical Universe. However, he has been recently focusing more on artificial intelligence research. He co-founded the Future of Life Institute and also has organized conferences with speakers such as Elon Musk, Demis Hassabis, Stuart Russell and others. The Future of Life Institute has already received donations from various business leaders to investigate risks posed by advanced artificial intelligence. In Life 3.0, we can read a fictitious story about Prometheus, advanced artificial general intelligence (AGI) created by Team Omega. In this story, Tegmark illustrates what could happen if such AGI is developed and how Team Omega can use Prometheus to take over the world. The book also refers to the world's leading companies which are focusing on creating AGI like DeepMind or OpenAI. It is a must-read for everyone who would like to see how our life could look in the future.

The Singularity is Near: When Humans Transcend Biology

Ray Kurzweil is a well-known inventor and entrepreneur, currently a Chief Engineer at Google. He accepted an offer from Google after publishing his book called How to Create a Mind (2012). In his theory, he explains that the brain consists of a hierarchy of pattern recognizers and suggests that techniques like the Hidden Markov models and genetic algorithms will be used for creating brain-like AGI architecture in the future. He is also known for successfully predicting many technological breakthroughs. He first mentioned a couple of predictions in The Age of Intelligent Machines (1990). Many of his predictions were successful and he continued to make more such predictions in The Singularity is Near. It is important to mention, however, that some of his predictions were not correct. That said, it is very impressive to successfully predict a number of well-defined events 15-20 years in the future. It is a very interesting and thought-provoking read.

AI Super-Powers: China, Silicon Valley and the New World Order

This is one of the most important books for every business leader in the current AI ecosystem. Kai-Fu Lee is one of a few entrepreneurs who have experiences in both Silicon Valley and China. He has worked at both Microsoft and Google, and provides very useful insights into today's AI race between the US and China. This is a must-read for everyone serious about building AI-driven products.

The Master Algorithm: How The Quest For Ultimate Learning Machine Will Remake Our World

This is a slightly more technical book than the others listed above. Pedro Domingos is a professor at the University of Washington and a machine learning researcher. He is known for his work on Markov logic networks. He describes the primary machine learning philosophies such as inductive reasoning, connectionism, evolutionary approaches, approaches based on Bayes' theorem, and others. He uses a lot of examples and analogies to the real world, and the book is a very helpful read for people without a technical background who are trying to understand the main directions the field is taking.

The Hundred-Page Machine Learning Book

This is the most technical book from the list, but it is still very accessible to beginners. I can see this book as a great fit for people with only a software engineering background who would like to get more technical insights into the machine learning field. Andriy Burkov is a lead data scientist at Gartner. Fitting the basics of the main machine learning methods in 100-150 pages is a very difficult task, but Andriy did it successfully. There are, however, much better choices for gaining in-depth knowledge in the field. This includes classic titles like Deep Learning (Adaptive Computation and Machine Learning Series) or Artificial Intelligence - A Modern Approach.

Conclusion

This list of books is great to get up to speed with the current AI ecosystem. It is important to recognize and be careful about being too optimistic about current AI capabilities. We might, for example, get easily caught up in the idea of exponential growth, which to certain extent, is valid. Nonetheless, our prediction models are just an approximation of the world and reality is usually much more complex.

Did you like this post? Be sure to subscribe to get notified about new articles on building AI-first companies.
Feel free to send any questions about the topic to david@atheros.ai.

Disclaimer: We might get a small referral fee if you buy some of the books through the links on this page. However, our commission does not affect the final Amazon price.

How to Build GraphQL APIs for Text Analytics in Python

David Mraz — Mon, 13 Jan 2020 10:21:51 +0000

Introduction

GraphQL is a query language and a server-side runtime environment for building APIs. It isn't tied to any specific database or programming language, meaning you can build your GraphQL server in Node.js, C#, Scala, Python and more. The ecosystem in JavaScript is the most evolved GraphQL-wise and it is usually better for client-facing APIs and frontend applications. You can take a look at our blog to learn more about building software with React, GraphQL, and Node.js. However, Node.js is not the best fit for data science, so in this article, we will take a look at building microservices with a GraphQL API. This will help us better serve our machine learning models and improve functionality for other computations like text analytics.

Running Flask server

Flask is a minimalist framework for building Python servers. At Atheros, we use Flask to expose our GraphQL API to serve our machine learning models. Requests from client applications are then forwarded by the GraphQL gateway. Overall, microservice architecture allows us to use the best technology for the right job, and and it also allows us to use advanced patterns like schema federation. In this article, we will start small with the implementation of the so-called Levenshtein distance. We will use the well-known NLTK library and expose the Levenshtein distance functionality with the GraphQL API. In this article, we assume that you are familiar with basic GraphQL concepts like building GraphQL mutations.

Let's start by cloning our example repository with the following:

git clone git@github.com:atherosai/next-react-graphql-apollo-hooks.git

In our projects, we use Pipenv for managing Python dependencies. If you are located in the project folder we can create our virtual environment with this:

pipenv shell

and install dependencies from Pipfile:

pipenv install

We usually define a couple of script aliases in our Pipfile to ease our development work-flow.

[scripts]
dev = "env FLASK_APP=app.py env FLASK_ENV=development flask run"
prod = "env FLASK_APP=app.py env FLASK_ENV=production gunicorn --bind 0.0.0.0:5000 -w 8 wsgi:app --timeout 10000"
test = "python -m pytest"
test-watch = "ptw --runner 'python -m pytest -s'"

It allows us to run our dev environment easily with a command alias as follows:

pipenv run dev

The Flask server should be then exposed by default at port 5000. You can immediately move on to GraphQL Playground, which serves as the IDE for the live documentation and query execution for GraphQL servers. GraphQL Playground uses the so-called GraphQL introspection for fetching information about our GraphQL types. The following code initialises our Flask server:

from flask import Flask, render_template, request
from flask_graphql import GraphQLView
from server.schema.Schema import Schema

app = Flask(__name__, static_url_path='', template_folder='./public', static_folder='./public')


@app.route('/')
def hello_world():
    return app.send_static_file('index.html')

@app.errorhandler(404)
@app.route("/404")
def page_not_found(error):
    return app.send_static_file('404.html')

@app.errorhandler(500)
@app.route("/500")
def requests_error(error):
    return app.send_static_file('500.html')

#point GraphQL playground to /graphql endpoint

app.add_url_rule(
    '/graphql',
    view_func=GraphQLView.as_view(
    'graphql',
    schema=Schema,
    #pass request to context to perform resolver validation
    get_context=lambda: {'request': request}
))

@app.route('/graphiql')
def playground_render():
    return app.send_static_file('playground.html')

if __name__ == "__main__":
    app.run(host='0.0.0.0')

It is a good practice to use the WSGI server when running a production environment. Therefore, we have also set-up a script alias for gunicorn with:

pipenv run prod

Levenshtein distance (edit distance)

The Levenshtein distance, also known as edit distance, is a string metric. It is defined as the minimum number of single-character edits needed to change a one character sequence a to another one b. We do not have support for math notation on this site, so for more on the theoretical background, feel free to check out the wiki.

In practice, let's say that someone misspelled "machine learning" and wrote "machinlt lerning". We would need to make the following edits:

Edit	Edit type	Word state
0	-	machinlt lerning
1	Substitution	machinet lerning
2	Deletion	machine lerning
3	Insertion	machine learning

For these two strings we get a Levenshtein distance equal to 3.
The Levenshtein distance has many applications, such as spell checkers, correction systems for optical character recognition, or similarity calculations.

Building a GraphQL server with graphene in Python

We will build the following schema in our article:

input LevenshteinDistanceInput {
  s1: String!
  s2: String!
  substitutionCost: Int = 1
  transpositions: Boolean = true
}

type LevenshteinDistancePayload {
  levenshteinDistance: Float
}

type Mutation {
  levenshteinDistance(
    input: LevenshteinDistanceInput!
  ): LevenshteinDistancePayload
}

type Query {
  healthcheck: Boolean!
}

Each GraphQL schema is required to have at least one query. We usually define our first query in order to healthcheck our microservice. The query can be called like this:

query {
  healthcheck
}

However, the main functional of our schema is to enable us to calculate the Levenshtein distance.
We will use variables to pass dynamic parameters in the following GraphQL document:

mutation levenshteinDistance($input: LevenshteinDistanceInput!) {
  levenshteinDistance(input: $input) {
    levenshteinDistance
  }
}

We have defined our schema so far in SDL format. In the Python ecosystem, however, we do not have libraries like graphql-tools, so we need to define our schema with a code-first approach. The schema is defined as follows using the Graphene library:


import graphene
import os
from server.schema.levenshtein_calc import LevenshteinDistanceMutation

class Query(graphene.ObjectType):
    healthcheck = graphene.Boolean(required=True)

    def resolve_healthcheck(self, info):
        return True


class Mutation(graphene.ObjectType):
    levenshtein_distance = LevenshteinDistanceMutation.Field()

Schema = graphene.Schema(query=Query, mutation=Mutation)

We have followed the best practices for overall schema and mutations. Our input object type is written in Graphene as follows:


import graphene

class LevenshteinDistanceInput(graphene.InputObjectType):
    s1 = graphene.String(required=True)
    s2 = graphene.String(required=True)
    substitution_cost = graphene.Int(default_value=1)
    transpositions = graphene.Boolean(default_value=True)

This code essentially defines dynamic arguments for our mutation. Those are then passed to the function responsible for calculating the Levenshtein distance.

Each time, we execute our mutation in GraphQL playground:

mutation levenshteinDistance($input: LevenshteinDistanceInput!) {
  levenshteinDistance(input: $input) {
    levenshteinDistance
  }
}

with the following variables

{
  "input": {
    "s1": "test1",
    "s2": "test2"
  }
}

we obtain the Levenshtein distance between our two input strings. For our simple example of strings test1 and test2, we get 1. We can leverage the well-known NLTK library for natural language processing (NLP). The following code is executed from our resolver:


import nltk

def calculate_levenshtein_distance(input):
    return nltk.edit_distance(s1=input["s1"], s2=input["s2"], substitution_cost=input["substitution_cost"], transpositions=input["transpositions"])

It is also straightforward to implement the Levenshtein distance by ourselves using, for example, an iterative matrix, but I would suggest to not reinvent the wheel and use the default NLTK functions.

Conclusion

GraphQL is a great technology for building APIs and it is very useful for exposing the output from machine learning models and other calculations. The Python ecosystem is more suitable for data science and libraries such as graphene help us build our GraphQL schema for machine learning microservices with ease.

Originally published at https://atheros.ai/blog/how-to-build-graphql-api-for-text-analytics-in-python

React Hooks in Apollo Client for GraphQL Queries and Mutations

David Mraz — Thu, 09 Jan 2020 14:14:15 +0000

Introduction

The hype following the last React conference has diminished. The proposal for React Hooks was introduced as part of the React alpha release. Since React v16.8, React Hooks have been in all official release as well. How does this improvement affect how we build our apps with GraphQL? We usually take our time before introducing new tech features in our projects at Atheros. This will allow us to not jump on the false hypes. React Hooks are now tested and production-ready, so we took a shot on implementing it in our projects as well. React Hooks is a new way how to reduce the need for React component classes and their life-cycle methods. They also solve other problems related to using HOC (Higher order component) or render props pattern. There are a lot of resources on React Hooks and I will not go deep into them from React standpoint in this article. You can check out the following talk from the recent conference

or the official documentation

The official React library comes with its own default Hooks such as useState, useContext, useEffect and others. But, The React library does not, however, contain Hooks for executing GraphQL queries and mutations in the Apollo client. Let's take a look at these now. First, let's summarize how we currently fetch data with Apollo and React.

Apollo client API

With the Apollo client and React, you can query your GraphQL server in various ways. We currently have three major ways to query our GraphQL server.

HOC pattern
Render props pattern
React Hooks

We will show how these approaches work using the simple component for displaying a list of emails. The GraphQL query looks like this:

query Subscriptions {
  subscriptions {
    id
    email
    source
  }
}

It will be useful to check out the repository with examples. You can clone the repository with...

git clone git@github.com:atherosai/next-react-graphql-apollo-hooks.git

and then, to preserve package-lock.json dependencies, install with...

npm ci

You can run dev server as follows...

npm run dev

HOC (Higher-Order-Component) pattern

As far as I know, this is the oldest execution method for queries and mutations with Apollo. It uses the well-known React HOC pattern. This pattern is implemented in React Apollo using the HOC component created with the graphql function. We can use this function to define further HOCs for a different GraphQL query or mutation. With this approach, we can write our simple component as follows:

import React from 'react';
import { graphql } from '@apollo/react-hoc';
import get from 'lodash.get';
import SUBSCRIPTIONS_QUERY from './Subscriptions.graphql';
import s from './SubscriptionTable.scss';
const withSubscriptionQuery = graphql(SUBSCRIPTIONS_QUERY);
const SubscriptionsTable = ({ data }) => {
    return (
    <div className={s.SubscriptionTable}>
        <div className={s.SubscriptionTable__Header}>Email</div>
        {get(data, 'subscriptions', []).map(subscription => (
            <div key={get(subscription, 'id')} className={s.SubscriptionTable__Row}>
            {get(subscription, 'email')}
            </div>
        ))}
    </div>
    );
};
export default withSubscriptionQuery(SubscriptionsTable);

The disadvantage can be that if we have many mutations or queries, it can become impractical to maintain so many HOCs. In some cases, you even need to keep the HOCs in order if you use, for example, the with Apollo component as well. In these cases, to clean up the code we can use compose utility from the React Apollo package, or just use the recompose library.

Render props pattern

This pattern was official one for quite some time in Apollo community. There is no need to wrap the components with HOCs. The HOCs created with graphql() had been replaced by the Query and Mutation components. The rewrite for our simple component above is easy.

import React from 'react';
import { Query } from '@apollo/react-components';
import get from 'lodash.get';
import SUBSCRIPTIONS_QUERY from './Subscriptions.graphql';
import s from './SubscriptionTable.scss';
const SubscriptionsTable = () => {
    return (
        <Query query={SUBSCRIPTIONS_QUERY}>
        {({ loading, error, data }) => {
            if (loading) return "Loading...";
            if (error) return \`Error! ${error.message}\`;

            return (
            <div className={s.SubscriptionTable}>
                <div className={s.SubscriptionTable__Header}>Email</div>
                {get(data, 'subscriptions', []).map(subscription => (
                    <div key={get(subscription, 'id')} className={s.SubscriptionTable__Row}>
                    {get(subscription, 'email')}
                    </div>
                ))}
            </div>)
        }}
        </Query>

    );
};
export default SubscriptionsTable;

You are still able to use either HOCs or render props in Apollo client, but both ways are now obsolete and replaced with official React Hooks. You can also check out this article on pros and cons of higher-order components, render props, and React Hooks.

Using React Hooks with GraphQL in the Apollo client

This section was significantly updated to be compliant with official Apollo client API

React Hooks now have official support in the React Apollo. The support of React Hooks is coming with some great improvements. First of all there is significant reduction in bundle size as you can use only @apollo/react-hooks package. Even though you can reinvent the wheel and try to prepare the Hooks by yourself, I would suggest to use already-prepared Hooks. With the new introduction of React Hooks in Apollo official release you would need to install dedicated packages for SSR. The first thing that you need to do is to wrap your top-level component with the Apollo provider. We use Next.js in our example project, so a good place to do it can be in __app.js file as follows:

import React from 'react';
import get from 'lodash.get';
import App, { Container } from 'next/app';
import { ApolloProvider } from '@apollo/react-hooks';
import Router from 'next/router';
import { pageview } from '../lib/gtag';
import { NODE_ENV, CUSTOM_ENV } from '../config/config';
import withApolloClient from '../lib/with-apollo-client';
import globalStyle from '../theme/global.scss';
if (CUSTOM_ENV === 'production') {
  Router.onRouteChangeComplete = url => {
    pageview(url);
  };
}
class MyApp extends App {
  componentDidMount() {
    import('webfontloader').then(WebFont =>
      WebFont.load({
        google: {
          families: ['Montserrat']
        }
      })
    );
    if ('serviceWorker' in navigator && NODE_ENV === 'production') {
      get(navigator, 'serviceWorker').register('/service-worker.js');
    }
  }
  render() {
    const { Component, pageProps, apolloClient } = this.props;
    return (
      <Container>
        <ApolloProvider client={apolloClient}>
          <div className={globalStyle.Global}>
            <Component {...pageProps} />
          </div>
        </ApolloProvider>
      </Container>
    );
  }
}
export default withApolloClient(MyApp);

However, this is only good approach if you use Next.js with server side rendering (SSR) and fetch data from GraphQL on majority of your pages. For pages that do not need to be server side rendered you can use HOC to inject Apollo Provider on per page bases as follows:

import React from 'react';
import { ApolloProvider } from '@apollo/react-hooks';
import ApolloClient from 'apollo-client';
import { NormalizedCacheObject } from 'apollo-cache-inmemory';
import { IS_PROD } from '../config/config';
import initApollo from './init-apollo';


interface AppPropsI {
  apolloClient: ApolloClient<NormalizedCacheObject>;
}

interface ApolloPropsI {
  apolloState: NormalizedCacheObject;
}
// should be used for pages, which should not be server side renderer
const withApolloClientStatic: Function = (App: React.FunctionComponent<AppPropsI>) => {
  const Apollo: React.FunctionComponent<ApolloPropsI> = ({ apolloState }: ApolloPropsI) => {
    const apolloClient = initApollo(apolloState);
    return (
      <ApolloProvider client={apolloClient}>
        <App apolloClient={apolloClient} />
      </ApolloProvider>
    );
  };

  // Set the correct displayName in development
  if (!IS_PROD) {
    const displayName = Apollo.displayName || Apollo.name || 'Component';

    if (displayName === 'App') {
      // eslint-disable-next-line no-console
      console.warn('This withApollo HOC only works with PageComponents.');
    }

    Apollo.displayName = `withApollo(${displayName})`;
  }

  return Apollo;
};

export default withApolloClientStatic;

The Apollo Provider enables us to use React Hooks for executing queries and mutations in our application. The following Hooks are available in the official Apollo release: useQuery, useLazyQuery, useMutation, useSubscription and useApolloClient.

GraphQL queries with React Apollo Hooks

Let's take a look at the component for fetching emails that we wrote with the HOC and render props pattern. We will import the useQuery Hook from the officialReact Apollo Hooks library. Now let's define our first Hook for a GraphQL query. Hooks need to be defined in the body of functional React components. The new implementation with React Hooks is as follows:

import React from 'react';
import get from 'lodash.get';
import uuid from 'uuid/v1';
import { useQuery } from '@apollo/react-hooks';
import SUBSCRIPTIONS_QUERY from './SUBSCRIPTIONS.graphql';
import { SubscriptionsQuery, SubscriptionsQueryVariables } from '../../../__generated__/typescript-operations';
import s from './SubscriptionsTable.scss';

const SubscriptionsTable: React.FunctionComponent = () => {
  const { data, loading, error } = useQuery<SubscriptionsQuery,
  SubscriptionsQueryVariables>(SUBSCRIPTIONS_QUERY);

  if (loading) return <>Loading...</>;
  if (error) return <>{`Error! ${error.message}`}</>;

  return (
    <div className={s.SubscriptionTable}>
      <table>
        <thead>
          <tr>
            <th>Email</th>
            <th>Source</th>
          </tr>
        </thead>
        <tbody>
          {data && data.subscriptions && data.subscriptions.map((subscription) => (
            <tr key={get(subscription, 'id', uuid())}>
              <td>
                {get(subscription, 'email')}
              </td>
              <td>
                {get(subscription, 'source')}
              </td>
            </tr>
          ))}
        </tbody>
      </table>

    </div>
  );
};

export default SubscriptionsTable;

We can see that the API is simple to use, and also the useQuery Hook returns the same variables as usual. You might also notice that we have pre-generated our TypeScript types. For more information you can follow our previous article.

Now let's take a look at how we can define variables and manually update the cache.

Writing our GraphQL mutations with React Hooks

We can define the useMutation in a similar way. As we know, the main difference between a query and a mutation lies in their different execution. Queries are executed in parallel, but mutations are executed serially. Let's take a look at how to execute the subscribeEmail mutation

mutation Subscribe($input: SubscribeInput!) {
  subscribe(input: $input) {
    id
    email
    source
  }
}

using the useMutation Hook.

/* eslint-disable jsx-a11y/label-has-for */
import React from 'react';
import { useMutation } from '@apollo/react-hooks';
import {
  Formik, ErrorMessage, Form, Field,
} from 'formik';
import * as Yup from 'yup';
// eslint-disable-next-line import/no-extraneous-dependencies
import { FetchResult } from 'apollo-link';
import get from 'lodash.get';
import s from './Subscription.scss';
import SUSCRIBE_MUTATION from './SUBSCRIBE.graphql';
import SUBSCRIPTIONS_QUERY from '../SubscriptionsTable/SUBSCRIPTIONS.graphql';
import { SubscribeMutation, SubscribeMutationVariables, Query } from '../../../__generated__/typescript-operations';

interface InitialValuesI {
  email: string;
}
interface HandleSubscribeI {
  values: InitialValuesI;
  subscribeMutation: Function;
  resetForm: Function;
}


const handleSubsribe: Function = async ({
  values,
  subscribeMutation,
  resetForm,
}: HandleSubscribeI) => {
  const subscribeResult: Promise<SubscribeMutation> = await subscribeMutation({
    variables: {
      input: {
        source: 'HOME_PAGE',
        ...values,
      },
    },
  });

  if (get(subscribeResult, 'data.subscribe')) {
    resetForm();
  }

  return subscribeResult;
};


const Subscription: React.FunctionComponent = () => {
  const [subscribeMutation] = useMutation<SubscribeMutation, SubscribeMutationVariables>(
    SUSCRIBE_MUTATION,
    {
      update: (cache, { data }: FetchResult): void => {
        const dataResult = cache.readQuery<Query>({ query: SUBSCRIPTIONS_QUERY });
        cache.writeQuery({
          query: SUBSCRIPTIONS_QUERY,
          data: {
            subscriptions: dataResult
            && dataResult.subscriptions
            && dataResult.subscriptions.concat([data && data.subscribe]),
          },
        });
      },
    },
  );
  const initialValues: InitialValuesI = {
    email: '',
  };
  return (
    <div className={s.Subscription}>
      <div className={s.Subscription__SubscriptionWrapper}>
        <div>
          <h2>
            Lorem ipsum is placeholder text commonly used in the graphic, print, and publishing
            industries for previewing layouts and visual mockups.
          </h2>
          <Formik
            initialValues={initialValues}
            onSubmit={async (values, { resetForm }): Promise<SubscribeMutation> => handleSubsribe({
              values,
              subscribeMutation,
              resetForm,
            })}
            validationSchema={Yup.object().shape({
              email: Yup.string()
                .email()
                .required('Before submitting you need to provide your email'),
            })}
          >
            <Form>
              <div className={s.Subscription__Row}>
                <label htmlFor="email">Email</label>
                <Field
                  id="email"
                  className={s.Carousel__EmailInput}
                  name="email"
                  placeholder="your@email.com"
                  type="email"
                />
                <button type="submit" className={s.Subscription__SubscribeButton}>
                    Subscribe
                </button>
              </div>
              <div className={s.Subscription__FieldErrorRow}>
                <ErrorMessage
                  name="email"
                  component="div"
                  className={s.Subscription__FieldError}
                />
              </div>
            </Form>
          </Formik>
        </div>
      </div>
    </div>
  );
};

export default Subscription;

We have written our component with the excellent Formik and Yup validation library. We can see that the Hooks definition is done without variables. In the React Apollo library, we can either define variables in the body of a functional component or pass them dynamically once the Hook is executed.

Conclusion

I hope that you like this short article on using React Hooks with GraphQL. We really enjoy using Hooks with unofficial community library and now with official Apollo support it gets even better. To ease your Hooks set-up with Apollo, you can use our example repository to speed up the process.

Did you like this post? You can clone the repository with the examples and project set-up here.
Feel free to send any questions about the topic to david@atheros.ai.

This article was originally published at https://atheros.ai/blog/react-hooks-in-apollo-client-for-graphql-queries-and-mutations