GraphQL

Hasura, GraphQL Backend in the Cloud- Part 2

Published Oct 28, 2019

Updated Feb 14, 2023

14 min read

2 Part Series

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

In Part One, you were introduced to the Hasura GraphQL Engine and shown how to deploy and use Hasura on Heroku.

In this instalment, we will continue where we left off and move on to explore the extensions Hasura offers for the standard GraphQL queries and mutations. At the end of this part, we will set the ground for Part Three and learn more about Hasura Authorization and Dynamic Access Control.

So far, you have learned how Hasura auto-generates queries and mutations of the GraphQL schema from your Postgres schema model. Also, it generates a range of possible queries that could be used. For instance, depending on the Primary Key of a table, it generates a query field that accepts an ID and returns a single object based on that ID input parameter. In addition, Hausra detects relationships between database tables and generates those as nested objects respectively.

The recipe query field that is auto-generated by Hasura is as shown. The rest of the query and mutation fields can be checked on Hasura app deployed on Heroku.

recipe(limit: Int offset: Int order_by: [recipe_order_by!] where: recipe_bool_exp): [recipe!]!
fetch data from the table: "recipe"

The recipe mutation field is auto-generated as well, and its results are as shown too. The details of the object types created by Hasura can be checked on Hasura app deployed on Heroku.

insert_recipe(objects: [recipe_insert_input!]! on_conflict: recipe_on_conflict): recipe_mutation_response
insert data into the table: "recipe"

GraphQL Mutations

We will explore a few mutations to demonstrate the different extensions Hasura adds to GraphQL standard language.

Insert Single record

Let’s start by inserting a new ingredient:

mutation insertSaltIngredient {
  insert_ingredient(objects: [{name: "Salt"}]) {
    returning {
      name
    }
  }
}

Hasura adds the objects type that can hold a single or multiple data records for insertion.

The mutation above creates the Salt ingredient and returns the name of the newly inserted ingredient.

{
  "data": {
    "insert_ingredient": {
      "returning": [
        {
          "name": "Salt"
        }
      ]
    }
  }
}

Insert Bulk of records,

To insert ingredient records in bulk you can pass multiple data records inside the objects type to the mutation insertIngredients:

mutation insertIngredients {
  insert_ingredient(objects: [{name: "White sugar"}, {name: "Garlic"}]) {
    returning {
      name
    }
  }
}

Insert a record with a nested object record at once

You can insert a new record together with a nested object all at once. For instance, I can write a mutation to insert a new recipe object labeled Pizza together with a nested object, of type recipe_ingredients, in a single mutation.

The assumption here is that the ingredient object already exists in the database.

mutation insertRecipe {
  insert_recipe(objects: [{name: "Pizza", description: "Preparing a lovely Margartia Pizza", vegeterian: true, recipe_ingredients: {data: [{ingredient_id: 3, quantity: 2, comments: "Medium tomatoes"}]}}]) {
    returning {
      name
    }
  }
}

With a single mutation, you are able to insert a new record in the recipe table together with a record in the many-to-many relationship table, the recipe_ingredient.

If the ingredient you are inserting inside the recipe_ingredient doesn’t exist in the database, Hasura GraphQL mutations allows you to insert a new recipe, together with a new recipe_ingredient and a new ingredient, all done at once in the same query and handled totally by Hasura!

Check the mutation below:

mutation insertRecipe {
  insert_recipe(objects: [{name: "Pizza", description: "Preparing a lovely Margartia Pizza", vegeterian: true, recipe_ingredients: {data: [{ingredient: {data: {name: "Tomato"}}, quantity: 2, comments: "Medium tomatoes"}]}}]) {
    returning {
      name
    }
  }
}

The mutation is inserting a new Pizza recipe together with a new Tomato ingredient and finally inserting the relationship record between the two objects as a new recipe_ingredient object relationship.

Upsert a record in Postgres database with GraphQL

Upserting a record in the database is to execute a single mutation statement such that, when the record already exists in the database, it gets updated. While, if the record doesn’t exist in the database, it gets created. The upsert operation is based on constraints that we will cover next .

Let’s explore how Hasura converted the table ingredient into a GraphQL mutation statement with all the related object types.

insert_ingredient(objects: [ingredient_insert_input!]!on_conflict: ingredient_on_conflict): ingredient_mutation_response
insert data into the table: "ingredient"

The insert_ingredient mutation accepts both objects and on_conflict input parameters. We have seen how to use the objects parameter to pass the actual data to be inserted inside the database. The on_conflict parameter is basically used to upgrade an insert statement into an upsert statement to help Hasura make a decision when there is a conflict in the data being inserted.

The ingredient_on_conflict object is defined as an object with the following properties:

constraint: ingredient_constraint!
update_columns: [ingredient_column!]

The ingredient_constraint object is defined as a constraint on the Primary Key of the table ingredients:

Ingredient_pkey
unique or primary key constraint

When a new ingredient is inserted into the database:

A conflict occurs on the constraint defined in constraint property:n this case, the ingredient_constraint. It means we are trying to insert a new record with a Primary Key of ID that already exists in the database table.

Hasura checks the update_columns property.

If update_columns property is omitted in the ingredient_constraint, it updates the record found in the table with all the columns included in the objects parameter.

mutation insertSaltIngredient {
  insert_ingredient(objects: [{id: 2, name: "Eggs"}], on_conflict: {constraint: ingredient_pkey}) {
    returning {
      id
      name
    }
  }
}

If the property exists, Hasura will perform an update operation and update only those columns listed in the update_columns array.

mutation insertSaltIngredient {
  insert_ingredient(objects: [{id: 2, name: "Eggs"}], on_conflict: {constraint: ingredient_pkey, update_columns: [name]}) {
    returning {
      id
      name
    }
  }
}

On the other hand, if the update_columns property exists and is set to a value of an empty array, the insert operation is ignored.

mutation insertSaltIngredient {
  insert_ingredient(objects: [{id: 2, name: "Eggs"}], on_conflict: {constraint: ingredient_pkey, update_columns: []}) {
    returning {
      id
      name
    }
  }
}

Update a record using a where operator

Hasura offers the where operator to filter out records to be updated in the mutation. The mutation below updates the ingredient record with id = 2 and sets its name to Eggs.

mutation {
  update_ingredient(where: {id: {_eq: 2}}, _set: {name: "Eggs"}) {
    returning {
      id
      name
    }
  }
}

Update a record using a where operator on nested object property

An update mutation can also be used to update a record filtered by a property on one of its nested object properties.

mutation {
  update_recipe(where: {food_category: {id: {_eq: 2}}}, _set: {name: "Update based on food_category"}) {
    returning {
      id
      name
      food_category_id
    }
  }
}

The mutation above loops through all recipe records in the database and updates their name column value to “Update based on food_category” where the food_category’s id = 2. And the result is:

{
  "data": {
    "update_recipe": {
      "returning": [
        {
          "id": 4,
          "name": "Update based on food_category",
          "food_category_id": 2
        },
        {
          "id": 5,
          "name": "Update based on food_category",
          "food_category_id": 2
        }
      ]
    }
  }
}

Update a record property of type jsonb

Hasura supports updating records with columns of type jsonb in Postgres. You can read more on this topic by following this link: Using Jsob operators.

Delete a record using a where operator

To delete a record in Hasura you can execute the delete mutation and filter on the record to be deleted:

mutation {
  delete_recipe(where: {name: {_like: "%za%"}}) {
    returning {
      id
      name
    }
  }
}

The mutation above deletes the recipe with name ends with za.

Delete a record using a where operator on nested object property

You may also delete a record filtered through a nested object property as follows:

mutation {
  delete_recipe(where: {food_category: {name: {_eq: "Desserts"}}}) {
    returning {
      id
      name
    }
  }
}

The above mutation deletes a recipe record whose food_category name is “Desserts.”

GraphQL Queries

Now that we’ve built up some data in our Postgres database, let’s explore queries and what Hasura offers in this regard.

Simple Query

Let’s start by writing a simple query to retrieve all recipes in the database and return only the id and name of each recipe:

query getAllRecipes {
  recipe {
    id
    name
  }
}

The query above returns the following response:

{
  "data": {
    "recipe": [
  	{
        "id": 1,
        "name": "Hamburger Steak with Onions and Gravy"
  	},
  	{
        "id": 2,
        "name": "Butter!"
  	}
	]
  }
}

Query a record and return nested object fields (object relationship)

A typical GraphQL query would be to search for a record and also return data from its nested objects in an object relationship.

query getAllRecipes {
  recipe(where: {id: {_eq: 1}}) {
    id
    name
    food_category {
      id
      name
    }
  }
}

This query is for a recipe whose id = 1 and returns the id and name of the recipe and the id and name of the food_category.

{
  "data": {
    "recipe": [
      {
        "id": 1,
        "name": "Hamburger Steak with Onions and Gravy",
        "food_category": {
          "id": 5,
          "name": "BBQ and Grilled Beef"
        }
      }
    ]
  }
}

Query a record and return nested object fields (array relationship)

A typical GraphQL query is to search for a record and also return data from its nested objects in an array relationship.

query getAllRecipes {
  recipe(where: {id: {_eq: 6}}) {
    id
    name
    recipe_ingredients {
      ingredient {
        name
      }
      quantity
      comments
    }
  }
}

The query above returns the recipe with id = 6 and also returns all the ingredients defined by the recipe_ingredients relationship:

{
  "data": {
    "recipe": [
      {
        "id": 6,
        "name": "Butterhorns",
        "recipe_ingredients": [
          {
            "ingredient": {
              "name": "White sugar"
            },
            "quantity": 2,
            "comments": "teaspoons"
          },
          {
            "ingredient": {
              "name": "Milk"
            },
            "quantity": 1,
            "comments": "cups"
          },
          {
            "ingredient": {
              "name": "Butter, softened"
            },
            "quantity": 1,
            "comments": "cup"
          },
          {
            "ingredient": {
              "name": "Eggs"
            },
            "quantity": 3,
            "comments": "eggs"
          }
        ]
      }
    ]
  }
}

Query a record using the Greater Than operator

Let’s say we want to query for a recipe that serves more than four people. Hasura offers an out of the box list of useful operators that you can use inside the GraphQL queries.

{
  recipe(where: {number_of_servings: {_gt: 4}}) {
    id
    name
    number_of_servings
  }
}

The query above makes use of the _gt operator to filter out all recipes serving more than four persons and requesting in return the recipe id, name and number of servings columns:

{
  "data": {
    "recipe": [
      {
        "id": 6,
        "name": "Butterhorns",
        "number_of_servings": 16
      }
    ]
  }
}

Hasura also offers other related operators like: _gte,_lt and _lte.

Query a record using the Equality operators

Let’s query the Eggs ingredient using the _eq operator.

{
  ingredient(where: {name: {_eq: "Eggs"}}) {
    id
    name
  }
}

Likewise, you can use the _neq operator to exclude some data.

{
  ingredient(where: {name: {_neq: "Eggs"}}) {
    id
    name
  }
}

This query returns all ingredients to exclude Eggs.

Query a record using the List based Search operators

Hasura brings to the GraphQL table many SQL based operators that powers up the GraphQL queries.

For instance, let's query all recipes that belong to food_category 1 and 2.

{
  recipe(where: {food_category: {id: {_in: [1, 2]}}}) {
    id
    name
    food_category {
      id
    }
  }
}

The response is as follows:

{
  "data": {
    "recipe": [
      {
        "id": 4,
        "name": "Cajun Seafood Pasta",
        "food_category": {
          "id": 2
        }
      },
      {
        "id": 5,
        "name": "Chicken Parmesan",
        "food_category": {
          "id": 2
        }
      }
    ]
  }
}

Notice how the query returns the food_category id field to verify the query sent?

Likewise, Hasura offers the _nin operator which functions in the opposite direction to _in operator.

Query a record using the Text Search or pattern operators

Hasura offers the _like, _nlike, _ilike, _nilike, _similar and _nsimilar. These operators are the counterparts for SQL clauses. The _ilike operator is not case sensitive, whereas _like and _similar operators are case sensitive. In addition, you can use the _similar operator to do a pattern match searching.

Let’s query for all recipes that contain chicken in their names:

{
  recipe(where: {name: {_ilike: "%chicken%"}}) {
    id
    name
    food_category {
      id
    }
  }
}

Let’s run a query for all ingredients whose names start with the letter E or B.

{
  ingredient(where: {name: {_similar: "(E|B)%"}}) {
    id
    name
  }
}

Visit Hasura docs to check the rest of the operators offered.

Query all recipes and Sort results

Let’s query all recipes and use Hasura order_by operator to sort the results by recipe name in an ascending order.

{
  recipe(order_by: [{name: asc}]) {
    id
    name
  }
}

The results are as follows:

{
  "data": {
    "recipe": [
      {
        "id": 6,
        "name": "Butterhorns"
      },
      {
        "id": 4,
        "name": "Cajun Seafood Pasta"
      },
      {
        "id": 5,
        "name": "Chicken Parmesan"
      },
      {
        "id": 1,
        "name": "Hamburger Steak with Onions and Gravy"
      }
    ]
  }
}

Query all recipes and Sort results by a Nested Object field

Let’s say we want to query for all recipes and sort the results by the nested object food_category name.

{
  recipe(order_by: [{food_category: {name: desc}}]) {
    id
    name
    food_category {
      name
    }
  }
}

The query searches for all recipes and orders the results by the food_category name on each recipe.

{
  "data": {
    "recipe": [
      {
        "id": 4,
        "name": "Cajun Seafood Pasta",
        "food_category": {
          "name": "Seafood"
        }
      },
      {
        "id": 5,
        "name": "Chicken Parmesan",
        "food_category": {
          "name": "Seafood"
        }
      },
      {
        "id": 6,
        "name": "Butterhorns",
        "food_category": {
          "name": "Bread"
        }
      },
      {
        "id": 1,
        "name": "Hamburger Steak with Onions and Gravy",
        "food_category": {
          "name": "BBQ and Grilled Beef"
        }
      }
    ]
  }
}

The recipe with food_category name of Seafood comes first in the list before a recipe with food_category of Bread.

Query all recipes and return only the first N records

Hasura enriches GraphQL with a pagination mechanism that you can use to limit the number of records returned from a query.

{
  recipe(limit: 2, order_by: [{food_category: {name: asc}}]) {
    id
    name
    food_category {
      name
    }
  }
}

The query orders all recipes by the food_category names in an ascending order and returns only the first 2 records using the limit operator.

Let’s say we want to run the same query, however this time, we skip the first record and return the next 2 records.

{
  recipe(limit: 2, offset: 1, order_by: [{food_category: {name: asc}}]) {
    id
    name
    food_category {
      name
    }
  }
}

The offset operator lets you define the number of records to skip. The limit and offset operators are very useful when you want to introduce paging into your result sets.

Mixing multiple operators in the same Query

Let’s write a query to ask for all the recipes that serve more than four persons, skip the first two records, return five records, and order the results by recipe name in a descending order. Phew!

{
  recipe(where: {number_of_servings: {_gt: 4}}, limit: 5, offset: 2, order_by: {name: desc}) {
    id
    name
    number_of_servings
  }
}

GraphQL Subscriptions

A GraphQL subscription is a live query where the client receives an event that a field has changed its value on the server. Hasura has full support for subscriptions.

Event Triggers

Hasura provides event triggers for the Postgres tables. You can define your own trigger based on a delete, insert, or update operation. For each trigger, you would also define a webhook that Hasura will call via a POST request upon a delete, insert, or update event on the database tables.

Authentication / Access Control

Hasura offers a powerful yet easy to use access control system that gives the developer the upper hand in defining a very granular and fine tuned access control strategy to control every field in the GraphQL schema which is eventually a table in the database.

Not only that, Hasura also allows you to utilize dynamic variables, that we will discuss further down the line, in the access control strategies to give more preciseness and control.

In addition to controlling queries and mutations on GraphQL schema fields, you can be selective in what table columns can be queried, inserted, updated or deleted.

Basic Access Control

Let’s modify the recipe table by adding the created_by column. This column holds the user who actually inserted the recipe.

Refer back to Part one of this series for more details on how to modify a Postgres table managed by Hasura.

Now that the column is added, lets navigate to the Permissions tab on the recipe table.

By default, Hasura creates for each and every table an admin Role. This role has full access on the table and all of its columns.

To add a custom access control strategy, start by creating a new Role. By default every new role has no access to the table operations of insert, select, delete and update.

Enter the name of the new role and click on the pencil icon near each column (insert, select, update and delete) to edit the permissions via an access control form.

To give the role user select permission on the recipe table, you select the Without any checks checkbox.

To give the role user select permission on some columns of the recipe table, choose the columns for access, under With access to columns section.

You can further customize your access control to compare the ID of the user executing the query against a static value or a value coming from a dynamic variable that Hasura has access to. For this, use the With custom check checkbox.

You need to follow the same steps highlighted above to give proper access control on other operations like insert, delete and edit. Otherwise, if left with no access this means Hasura will not generate the proper object types, queries and mutations corresponding to the other operations.

The above expression reads as follows:

Allow a user to read the data row whose created_by column value equals to the value stored in the dynamic session variable X-HASURA-USER-ID such that the user belongs to the role user.

When in development mode, you can pass the X-HASURA-USER-ID and X-HASURA-ROLE variables via the Request Headers. While in production mode, you are advised to hook Hasura with an Authorization/Authentication service that knows how to retrieve the X-HASURA-USER-ID and X-HASURA-ROLE values to man the access control.

To test it, switch to the API Explorer on Hasura, add the two variables as Request Headers and give them some values for testing.

You can always add more session variables to build more complex access control strategies. What matters is that Hasura gets access to those variables in order to evaluate your access control expressions.

Hasura online docs has an excellent article on constructing roles and permissions based on several practical scenarios. This article can be found under the Common roles and auth examples page.

Advanced Access Control

When in production, you don’t want to send Hasura the session variables in plain text via the Request Headers. Instead, you should authenticate the users of your client-side app with a public authentication service that generates for them an Authentication Token when they sign-in to your app.

When the app sends a request to the Hasura Engine to execute a query or mutation, the Authentication Token is included in the request headers.

Hasura then retrieves this token, sends its value to an authorization service to verify it, verify its holder and retrieve all the dynamic session variables from the token so that it can freely evaluate the access control expressions.

For the above workflow to function properly, Hasura Engine needs to be configured with a proper authorization webhook that can call to verify the tokens and retrieve the session variables.

For instance, in Part three of this series, when we build a Vue.js app. The app will make use of Auth0 to authenticate users of the app. Once a user is authenticated, an authentication token is generated. Usually, the app has access to the authentication token as it will send it together with the request to Hasura to include it in the request headers.

Hasura will be configured to call an Auth0 Webhook (developed and provided for free by Hasura) that would in return connect to auth0, verify the token and make sure it belongs to the user sending the original request and return to Hasura engine two session variables populated with the needed information.

The X-Hasura-User-Id will be populated by the Auth0 User ID.

The X-Hasura-Role will be populated by a default value of user.

In case the authorization fails, the response would include only the X-Hasura-Role with a value of anonymous.

In Part three we will deploy an instance of the Auth0 webhook on Heroku and configure Hasura to use that webhook to authenticate and authorize requests.

GraphQL Derived Views

As part of the tight integration between GraphQL and Postgres databases, Hasura allows for the creation of SQL Views on top of Postgres database. Once a view is created, Hasura makes sure to convert the view into a field on the Root Query and defines all type objects needed for this new field.

Hasura allows you to include the views as nested objects on other Root Query fields by letting you define relationships between a view and a table.

Let’s define our first view!

Navigate to the Data section of the Hasura Admin Console UI.

Click on the SQL section on the left hand side of the page.

We can type the SQL View in the SQL text area.

In this scenario, we are creating a view to only select the recipe id and name.

Notice the checkbox Track table is selected by default? When a view or table is tracked, Hasura will make sure that the view or table appear as a fields on the Root Query of the GraphQL schema type. This means, at any given moment you can ask Hasura to stop tracking a view or table, so their fields on the Root Query simply disappear!

Click on Run button to create the view. Notice how the Tables section now lists recipe_name_id view as new table?

Treat this new table like any other created with Hasura. You can now issue the usual GraphQL queries and mutations against this new field, even embed the recipe_name_id as a nested object on any other GraphQL type.

Another benefit of using Views as Tables in Hasura, is that you can select who to give access to and to what. Instead of adding permissions on the recipe table, you can now limit the permissions and apply them directly on the new view.

Check out Derived data in queries for more information on the topic.

Conclusion

This article covered most of the useful features in Hasura, enabling you to write GraphQL queries and mutations against your Postgres database. You can always refer back to the Hasura docs for a complete list of its features.

Part three is next. See you on the other side of this article!

Happy Hasuring!

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Bilal Haidar
Author, Developer, and Mentor: Professional ASP.NET 3.5 Security, Membership, and Role Management with C# and VB | A Complete Guide to VueJS
@bhaidar @bhaidar

Efficiently Extract Object References in Shopify Storefront GraphQL API

Efficiently Extract Object References in Shopify Storefront GraphQL API Introduction So, this blog post is born out of necessity and a bit of frustration. If you're diving into the world of Shopify's Storefront API, you've probably realized that while it's powerful, extracting data in the object reference from Metadata fields or Metaobjects (in the GraphQL query) can be a bit like searching for a needle in a haystack. This complexity often arises not from the API's lack of capabilities but from the sparse and sometimes unclear documentation on this specific aspect. That's precisely why I decided to create this post. As a developer, I found myself in a situation where the documentation and community resources were either scarce or not detailed enough for the specific challenges I faced. This guide is the result of my journey - from confusion to clarity. The Situation To understand the crux of my challenge, it's essential to recognize that creating metafields and metaobjects is a common practice for those seeking a more customized and controlled experience with Shopify CMS. In my specific case, I wanted to enrich the information available for each product's vendor beyond what Shopify typically allows, which is just a single text box. I aimed to have each vendor display their name and two versions of their logo: a themed logo that aligns with my website's color scheme and an original logo for use on specific pages. The challenge emerged when I fetched a list of all vendors to display on a page. My GraphQL query for the Storefront API looked like this: ` This was when I hit a roadblock. How do I fetch a field with a more complex type than a simple text or number, like an image? To retrieve the correct data, what specific details must I include in the originalLogo and themedLogo fields? In my quest for a solution, I turned to every resource I could think of. I combed through the Storefront API documentation, searched endlessly on Stack Overflow, and browsed various tech forums. Despite all these efforts, I couldn’t find the clear, detailed answers I needed. It felt like I was looking for something that should be there but wasn’t. Solution Before diving into the solution, it's important to note that this is the method I discovered through trial and error. There might be other approaches, but I want to share the process that worked for me without clear documentation. My first step was to understand the nature of the data returned by the Storefront API. I inspected the value of a metaobject, which looked something like this: ` The key here was the gid, or global unique identifier. What stood out was that it always includes the object type, in this case, MediaImage. This was crucial because it indicated which union to use and what properties to query from this object in the Storefront API documentation. So, I modified my query to include a reference to this object type, focusing on the originalLogo field as an example: ` The next step was to consult the Storefront API documentation for MediaImage at Shopify API Documentation. Here, I discovered the image field within MediaImage, an object containing the url field. With this information, I updated my query: ` Finally, when executing this query, the output for a single object was as follows: ` Through this process, I successfully extracted the necessary data from the object references in the metafields, specifically handling more complex data types like images. Conclusion In wrapping up, it's vital to emphasize that while this guide focused on extracting MediaImage data from Shopify's Storefront API, the methodology I've outlined is broadly applicable. The key is understanding the structure of the gid (global unique identifier) and using it to identify the correct object types within your GraphQL queries. Whether you're dealing with images or any other data type defined in Shopify's Storefront API, this approach can be your compass. Dive into the API documentation, identify the object types relevant to your needs, and adapt your queries accordingly. It's a versatile strategy that can be tailored to suit many requirements. Remember, the world of APIs and e-commerce is constantly evolving, and staying adaptable and resourceful is crucial. This journey has been a testament to the power of perseverance and creative problem-solving in the face of technical challenges. May your ventures into Shopify's Storefront API be equally rewarding and insightful....

Mar 29, 2024

4 mins

GraphQLShopify

Class and Enum Typings for Handling Data with GraphQL

Intro Today we’ll talk about class and enum typings for handling more complex data with GraphQL. The typings will be used on class objects to make them easier to read and understand. This blog will build on the concepts of another blog found here, in which I discussed wrapping and enhancing data, which talks about how to create a GraphQL Rest API wrapper, and how to enhance your data. This article assumes you have a basic understanding of classes, typing, and enums. Here is the code repo if you want to review it while reading, or just skip ahead. With that said, we will look at the class structure we’re going to be using, the enums, and the type lookup for our customField enum with our mapper. Class setup This class we’re going to set up will be strictly for typing. We’re going to make a RestaurantGuest class as this data will be restaurant themed. So in our restaurant.ts file, we will name it RestaurantGuest, and include a few different items. *Basic starting class example* ` After setting that up, we will add a type that will reference the above class. *Type example* ` This type will be used later when we do the type lookup in conjunction with our mapper function. With the above finished, we can now move on to handling our enums. Handling enums We’ll now create our Enum to make dealing with our complex data easier. Since the above 3249258 represents FoodReservation, we will create an enum for it. Now you might be wondering why 3249258 represents FoodReservation. Unfortunately, this is an example of how data can be returned to us from a call. It could be due to the field id established in a CMS such as Contentful, or from another source that we don’t control. This isn’t readable, so we’re creating an Enum for the value. *Enum example* ` This will be used later during our type look-up. Type lookup Now we can start combining the enum from above with our class type, and a look-up type that we’re about to create. So let's make another type called RestaurantGuestFieldLookup, which will have an id and value. *Look-up type example* ` Perfect, now we’ll swap out ` to be ` We can now move on to creating and using our mapper. In a separate file called mapper.ts, we will create our restaruantGuestMapper function. ` Tada! Thanks to all the work above, we can easily understand and get back the data we need. Conclusion Today's article covered setting up a typing class, creating an enum, and type lookup with a mapper for more complex data handling with GraphQL. Hopefully, the class structure was straightforward and helpful, along with the enums and type lookup and formatting examples. If you want to learn more about GraphQL, read up on our resources available at graphql.framework.dev....

May 26, 2023

2 mins

GraphQL

Nuxt.js for Complete Beginners

The Vuejs Amsterdam online conference was held at the end of February in 2021. It brought together Vue.js enthusiasts and community members from around the world. Many interesting topics were presented and covered. The focus, of course, was on Vue.js 3. In addition, the creators of Nuxt.js had the opportunity to showcase it from the current standpoint in development, to their intentions for it down the track. They even demonstrated a pre-alpha version of Nuxt.js 3, that’s based on Vue.js 3. This article will start by briefly covering general Nuxt.js concepts, creating a new Nuxt.js app using the create-nuxt-app CLI, and finally, going through the different files and folders that Nuxt.js auto-generates for us. Let’s start! Nuxt.js Concepts Nuxt.js is a web development framework that builds on top of the Vue.js framework. It allows you to use your Vue.js skills to build a more confident, structured, SEO friendly website purely in Vue.js. Remember when you had to mess with the Vue.js SSR module and the Vue Meta module to build a SEO friendly website? On top of that, you had to install and use Vuex and Vue Router too! Well, Nuxt.js takes care of that! No more chaotic setup and scaffolding to start a new Vue.js app. With the help of the create-nuxt-app CLI, you can scaffold a Nuxt.js app in no time. What’s remarkable about Nuxt.js is its capacity to enforce convention over configuration. This means, you write less configuration files by sticking to a specific directory structure that makes Nuxt.js happy and saves you a ton of time! Apps supported by Nuxt.js Nuxt.js supports building a variety of web apps, including the following: Server-Side Rendering (SSR) SSR apps are also known as Universal Apps. The app gets rendered on the server-side before it is sent to the client-side, and is displayed in the browser. This is the best option when working on an SEO friendly website written in Vue.js. You can read the full documentation for the SSR apps here: SSR Apps Single Page Apps (SPA) This is what you’ve been doing so far with Vue.js. The app is compiled into a few JS and CSS files. When the user requests the app, the files are downloaded to the client-side, and the Vue.js engine takes over rendering and displaying the app. Static Site Generation (SSG) Nuxt.js can pre-render your app at build time. This means the entire app will be converted to simple static HTML files that can be hosted and served over a Content Delivery Network (CDN). The SSG option makes an app a legal JAMStack app. You can read the full documentation for the Static Site Generation here: Static Site Generation. File System Routing Nuxt.js automatically generates all the Vue.js Routes in your app based on the folder structure inside the *pages* folder. For example, consider having this folder structure: ` Nuxt.js automatically generates the following route configuration: ` You can read about *File System Routing* here: File System Routing. Data Fetching Inside a Nuxt.js app, you can still use the old techniques you kmow when developing Vue.js apps. However, we have a new player here! Server-side rendering. Nuxt.js provides a new set of data-hooks that you can implement so that Nuxt.js can prefetch data when generating the app at the server-side. Here are two data-hooks offered by Nuxt.js: fetch() hook This hook was introduced with Nuxt.js 2.12+ release. It can be used inside Vue.js components stored in the *pages* folder and *components* folder. asyncData() hook This hook has been around for a while now, and can be used only inside the Vue.js components stored in the *pages* folder. You can read more about *Data Fetching* hooks here: Data Fetching. Meta Tags and SEO Nuxt.js makes it so intuitive to add SEO support to your SSR app. You can add Metadata to your app at two different levels: - Globally using the *nuxt.config.js* file - Locally inside a Nuxt.js Page You can read about *Meta Tags and SEO* hooks here: Meta Tags and SEO. Create our first Nuxt.js app Let’s use the create-nuxt-app CLI, and create our first Nuxt.js app! Before you start, you want to make sure you have all the perquisites required before you can install and run the CLI. For this article, I am going to use npx. However, you can also use npm, or feel free to use yarn. Step 0 Start by running the following command: ` This command uses the create-nuxt-app tool, and specifies the name of the project- in this case *my-first-nuxt-app*. The CLI will ask you a few questions that are important to scaffold the new Nuxt.js app based on your own preferences and decisions. Here’s what to expect. Step 1 First, let’s confirm the project name as shown in the Figure 1. Give the app a name and hit Enter. _Figure 1: Specify project name_ Step 2 You’ve got to choose whether you want to develop your app with TypeScript or JavaScript. I will select *JavaScript* as shown in Figure 2. _Figure 2: Programming language_ Step 3 Next, you need to choose between Npm or Yarn. I will select *Npm* as shown in Figure 3. _Figure 3: Package manager_ Step 4 In this step, you’ve got to select the UI framework you are going to use in the app. I will select *Tailwind CSS* as shown in Figure 4. Even if you skip this step, you can add any UI framework you want later. _Figure 4: UI framework_ Step 5 Nuxt.js offers a set of modules that you can use right away in your apps. For this app, I will pick the *Axios* module. Figure 5 shows the selection. _Figure 5: Nuxt.js modules_ Step 6 The CLI makes it super intuitive to integrate linters in your app. I will pick up both *ESLint* and *Prettier*. Figure 6 shows the selection. _Figure 6: Linting tools_ Step 7 Now it’s time to select a testing framework. For the sake of this article, I will select *None*. Feel free to add any. Figure 7 shows the selection. _Figure 7: Testing framework_ Step 8 By default, Nuxt.js supports two rendering modes. SSR/SSG and SPA. I will pick *SSR/SSG* to take advantage of the Server-side rendering. Figure 8 shows the selection. _Figure 8: Rendering mode_ Step 9 The deployment target depends on our selection in Step 8. In this case, we have two options to select from. Server (using a Node.js server hosting) or Static (CDN/JAMStack hosting). I will select the *Server* deployment target as shown in Figure 9. _Figure 9: Deployment target_ Step 10 For the development tools, I will keep it simple and select the *jsconfig.json* option as shown in Figure 10. _Figure 10: Development tools_ Step 11 I won’t be using any continuous integration for this app. I will simply select *None* as shown in Figure 11. _Figure 11: Continuous integration_ Step 12 Finally, the CLI asks whether you want to use any version control system. A version control system is always recommended when doing any kind of development. I will select *Git* as shown in Figure 12. _Figure 12: Version control system_ These twelve questions are enough for the CLI to start scaffolding and generating your app based on your preferences. It takes a few seconds to have everything ready for you. If all goes well, you should see the following as in Figure 13. _Figure 13: create-nuxt-app new app instructions_ The CLI gives you instructions on how to run and build the app. Step 13 Let’s run the app by following the steps highlighted in Figure 13. Run the following commands: ` The CLI compiles both the client and server parts of the app and starts the Node.js server on port 3000 as shown in Figure 14. _Figure 14: App is running_ Step 14 Open a browser instance and navigate to the URL *http://localhost:3000/* and you should see the default Nuxt.js app rendering. Figure 15 shows the app running in a browser. _Figure 15: App rendering in a browser_ That’s all you need to get started on your first Nuxt.js app. Enjoy! Nuxt.js Directory Structure Let’s quickly go through the different folders the CLI generated for us. I will start by opening the new app inside Visual Studio Code. Figure 16 shows the app open inside the editor. _Figure 16: App folders and files_ Let’s go through each folder, and explain their roles briefly. .nuxt The *.nuxt* folder is (re-)generated by the CLI every time you run or build the app. It has all the automatically generated files that Nuxt.js uses to run your app. You can read more about the *.nuxt* folder here: .nuxt. assets The *assets* folder contains all of your uncompiled files such as Sass files, images, or font files. Nuxt.js makes use of Webpack to load all the files inside this folder. You can read more about the *assets* folder here: assets. components This folder holds all of your Vue.js components. Nuxt.js components are not different from any other Vue.js component. Read more about the *components* folder here: components. layouts This folder contains all of your layout components. These are Vue.js components with placeholders for content. At run time, the component and the layout it uses get merged together into a single component. Layouts in Nuxt.js allows you to define fixed UI sections in your app instead of having to repeat things over and over. You can read more about the *layouts* folder here: layouts. pages This folder also holds Vue.js components. It is unique because Nuxt.js converts this folder structure (components with sub-folders) into actual Vue.js Routes. You can read about the *pages* folder here: pages. plugins This folder contains global JavaScript functions that you want to run before Nuxt.js instantiates the root Vue.js app. These functions are called *Plugins*. They can take multiple forms. For instance, you create a Nuxt.js Plugin to load a Vue.js Plugin to your app. You can also install, and make use of a third-party Nuxt.js Plugin. You can read more about the *plugins* folder here: plugins. static The name of this folder says it all! This folder is directly mapped to the server root. You can place any file in this folder that you do not want Webpack to process. For example, you can place a favicon file, any CSS files, and many other such files. You can read more about the *static* folder here: static. store The *store* folder holds all the Vuex store files. Nuxt.js comes with the Vuex module installed, but keeps it disabled. In order to enable the Vue store in your Nuxt.js app, create an *index.js* file inside this folder, and Nuxt.js will automatically enable it for you. You can read more about *store* folder here: store. nuxt.config.js As I mentioned, Nuxt.js prefers convention over configuration. However, at some times you may need to tweak the configuration a little. Nuxt.js provides the *nuxt.config.js* file to allow for custom configuration settings on the app level. Read more about *nuxt.config* file here: nuxt.config. That’s just a quick overview of what folders are generated by the Nuxt.js CLI. There are more you can read up on. You can find all the information you need on Nuxt.js Documentation website. Conclusion In this article, you were introduced to Nuxt.js and took a few baby steps towards creating your first Nuxt.js app. In the coming articles, we will immerse ourselves in the Nuxt.js world, and explore this fresh and promising web development framework together. You can follow me on Twitter to see more of my work....

Mar 22, 2021

12 mins

NuxtJSVue

Introduction to Zod for Data Validation

As web developers, we're often working with data from external sources like APIs we don't control or user inputs submitted to our backends. We can't always rely on this data to take the form we expect, and we can encounter unexpected errors when it deviates from expectations. But with the Zod library, we can define what our data ought to look like and parse the incoming data against those defined schemas. This lets us work with that data confidently, or to quickly throw an error when it isn't correct. Why use Zod? TypeScript is great for letting us define the shape of our data in our code. It helps us write more correct code the first time around by warning us if we are doing something we shouldn't. But TypeScript can't do everything for us. For example, we can define a variable as a string or a number, but we can't say "a string that starts with user_id_ and is 20 characters long" or "an integer between 1 and 5". There are limits to how much TypeScript can narrow down our data for us. Also, TypeScript is a tool for us developers. When we compile our code, our types are not available to the vanilla JavaScript. JavaScript can't validate that the data we actually use in our code matches what we thought we'd get when we wrote our TypeScript types unless you're willing to manually write code to perform those checks. This is where we can reach for a tool like Zod. With Zod, we can write data schemas. These schemas, in the simplest scenarios, look very much like TypeScript types. But we can do more with Zod than we can with TypeScript alone. Zod schemas let us create additional rules for data parsing and validation. A 20-character string that starts with user_id_? It's z.string().startsWith('user_id_').length(20). An integer between 1 and 5 inclusive? It's z.number().int().gte(1).lte(5). Zod's primitives give us many extra functions to be more specific about *exactly* what data we expect. Unlike TypeScript, Zod schemas aren't removed on compilation to JavaScript—we still have access to them! If our app receives some data, we can verify that it matches the expected shape by passing it to your Zod schema's parse function. You'll either get back your data in exactly the shape you defined in your schema, or Zod will give you an error to tell you what was wrong. Zod schemas aren't a replacement for TypeScript; rather, they are an excellent complement. Once we've defined our Zod schema, it's simple to derive a TypeScript type from it and to use that type as we normally would. But when we really need to be sure our data conforms to the schema, we can always parse the data with our schema for that extra confidence. Defining Data Schemas Zod schemas are the variables that define our expectations for the shape of our data, validate those expectations, and transform the data if necessary to match our desired shape. It's easy to start with simple schemas, and to add complexity as required. Zod provides different functions that represent data structures and related validation options, which can be combined to create larger schemas. In many cases, you'll probably be building a schema for a data object with properties of some primitive type. For example, here's a schema that would validate a JavaScript object representing an order for a pizza: ` Zod provides a number of primitives for defining schemas that line up with JavaScript primitives: string, number, bigint, boolean, date, symbol, undefined, and null. It also includes primitives void, any, unknown, and never for additional typing information. In addition to basic primitives, Zod can define object, array, and other native data structure schemas, as well as schemas for data structures not natively part of JavaScript like tuple and enum. The documentation contains considerable detail on the available data structures and how to use them. Parsing and Validating Data with Schemas With Zod schemas, you're not only telling your program what data should look like; you're also creating the tools to easily verify that the incoming data matches the schema definitions. This is where Zod really shines, as it greatly simplifies the process of validating data like user inputs or third party API responses. Let's say you're writing a website form to register new users. At a minimum, you'll need to make sure the new user's email address is a valid email address. For a password, we'll ask for something at least 8 characters long and including one letter, one number, and one special character. (Yes, this is not really the best way to write strong passwords; but for the sake of showing off how Zod works, we're going with it.) We'll also ask the user to confirm their password by typing it twice. First, let's create a Zod schema to model these inputs: ` So far, this schema is pretty basic. It's only making sure that whatever the user types as an email is an email, and it's checking that the password is at least 8 characters long. But it is *not* checking if password and confirmPassword match, nor checking for the complexity requirements. Let's enhance our schema to fix that! ` By adding refine with a custom validation function, we have been able to verify that the passwords match. If they don't, parsing will give us an error to let us know that the data was invalid. We can also chain refine functions to add checks for our password complexity rules: ` Here we've chained multiple refine functions. You could alternatively use superRefine, which gives you even more fine grained control. Now that we've built out our schema and added refinements for extra validation, we can parse some user inputs. Let's see two test cases: one that's bound to fail, and one that will succeed. ` There are two main ways we can use our schema to validate our data: parse and safeParse. The main difference is that parse will throw an error if validation fails, while safeParse will return an object with a success property of either true or false, and either a data property with your parsed data or an error property with the details of a ZodError explaining why the parsing failed. In the case of our example data, userInput2 will parse just fine and return the data for you to use. But userInput1 will create a ZodError listing all of the ways it has failed validation. ` ` We can use these error messages to communicate to the user how they need to fix their form inputs if validation fails. Each error in the list describes the validation failure and gives us a human readable message to go with it. You'll notice that the validation errors for checking for a valid email and for checking password length have a lot of details, but we've got three items at the end of the error list that don't really tell us anything useful: just a custom error of Invalid input. The first is from our refine checking if the passwords match, and the second two are from our refine functions checking for password complexity (numbers and special characters). Let's modify our refine functions so that these errors are useful! We'll add our own error parameters to customize the message we get back and the path to the data that failed validation. ` Now, our error messages from failures in refine are informative! You can figure out which form fields aren't validating from the path, and then display the messages next to form fields to let the user know how to remedy the error. ` By giving our refine checks a custom path and message, we can make better use of the returned errors. In this case, we can highlight specific problem form fields for the user and give them the message about what is wrong. Integrating with TypeScript Integrating Zod with TypeScript is very easy. Using z.infer<typeof YourSchema> will allow you to avoid writing extra TypeScript types that merely reflect the intent of your Zod schemas. You can create a type from any Zod schema like so: ` Using a TypeScript type derived from a Zod schema does *not* give you any extra level of data validation at the type level beyond what TypeScript is capable of. If you create a type from z.string.min(3).max(20), the TypeScript type will still just be string. And when compiled to JavaScript, even that will be gone! That's why you still need to use parse/safeParse on incoming data to validate it before proceeding as if it really does match your requirements. A common pattern with inferring types from Zod schemas is to use the same name for both. Because the schema is a variable, there's no name conflict if the type uses the same name. However, I find that this can lead to confusing situations when trying to import one or the other—my personal preference is to name the Zod schema with Schema at the end to make it clear which is which. Conclusion Zod is an excellent tool for easily and confidently asserting that the data you're working with is exactly the sort of data you were expecting. It gives us the ability to assert at runtime that we've got what we wanted, and allows us to then craft strategies to handle what happens if that data is wrong. Combined with the ability to infer TypeScript types from Zod schemas, it lets us write and run more reliable code with greater confidence....

Nov 15, 2024

7 mins

JavaScriptZod

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

2 Part Series

GraphQL Mutations

Insert Single record

Insert Bulk of records,

Insert a record with a nested object record at once

Upsert a record in Postgres database with GraphQL

Update a record using a where operator

Update a record using a where operator on nested object property

Update a record property of type jsonb

Delete a record using a where operator

Delete a record using a where operator on nested object property

GraphQL Queries

Simple Query

Query a record and return nested object fields (object relationship)

Query a record and return nested object fields (array relationship)

Query a record using the Greater Than operator

Query a record using the Equality operators

Query a record using the List based Search operators

Query a record using the Text Search or pattern operators

Query all recipes and Sort results

Query all recipes and Sort results by a Nested Object field

Query all recipes and return only the first N records

Mixing multiple operators in the same Query

GraphQL Subscriptions

Event Triggers

Authentication / Access Control

Basic Access Control

Advanced Access Control

GraphQL Derived Views

Conclusion

Bilal Haidar

Efficiently Extract Object References in Shopify Storefront GraphQL API

Class and Enum Typings for Handling Data with GraphQL

Nuxt.js for Complete Beginners

Introduction to Zod for Data Validation

Let's innovate together!

Efficiently Extract Object References in Shopify Storefront GraphQL API

Class and Enum Typings for Handling Data with GraphQL

Nuxt.js for Complete Beginners

Introduction to Zod for Data Validation