DEV Community: Andrew McCallum

Unions, Errors and __typenames - Type-Safe Error Handling in GraphQL

Andrew McCallum — Sat, 21 Jun 2025 14:43:50 +0000

I used to think handling errors in GraphQL was straightforward. Your query would return data and errors fields and you would use that to display the relevant information to the user. But it goes a little deeper than that. We're going to look at the different kinds of errors and how we take advantage of the __typename field.

Say you have a mutation for when a user signs up:

mutation signUp($input: SignUpInput!) {
  signUp(input: $input) {
    user {
      id
      email
      name
    }
  }
}

And from our app we might do something like this:

const [signUp, { data, error, loading }] = useMutation(signUpMutation)

if( error ) {
  // do something
}

const onSubmit = async (formData: FormData) => {
  await signUp({
    variables: {
      input: {
        email: formData.email,
        password: formData.password,
        name: formData.name,
      }
    }
  });
}

This works well - we are able to call our mutation on submit to register the new user, we then have a loading and error state that we can use to notify the user of what's happening.

Now imagine our backend throws an error to say that we already have a user registered with that email address and we want to notify the user that they actually already have an account. Our backend could throw an error and then we could pick that up on the frontend like so:

if( error ) {
  // check if it's an email error
  setError('email', error.message);
}

We then run into the issue of having to run some checks on the error to see what it's relevant to.

To make matters worse, GraphQL servers can technically return an error in any shape so we lose the nice schema validation that GraphQL would usually provide.

So how do we get around this?

Enter errors as data.

This is a way to allow us to return a union from our query or mutation whilst retaining some schema validation for the error returned.

mutation signUp($input: SignUpInput!) {
  signUp(input: $input) {
    ... on User {
      id
      email
      name
    }
    ... on ValidationError {
      field
      message
    }
  }
}

You can see here that we now return a union of User or ValidationError and we can see exactly what shape we are expecting back. We can even query the exact fields that we want.

Our app can now look something like this:

const [signUp, { data, error, loading }] = useMutation(signUpMutation)

if( error ) {
  // handle unexpected error
}

const onSubmit = async (formData: FormData) => {
  await signUp({
    variables: {
      input: {
        email: formData.email,
        password: formData.password,
        name: formData.name,
      }
    }
  });
}

// if ValidationError then show error messages for appropriate field

if (data) {
  // handle successful sign up, e.g., redirect to a welcome page
}

This raises the question: how do we distinguish a validation error from a successful response?

One common pattern I see is using type guards.

function isValidationError(response: User | ValidationError): response is ValidationError {
  return 'message' in response;
}

This might work fine initially but what if your query changes:
1) You query another union type that also has a message field.
2) The User type has a field named message.

Your isValidationError type guard will now return true even though there was no error.

This illustrates how brittle the type guard can be in this situation.

GraphQL provides a useful field called __typename that can help us in this situation. By querying the __typename field and using it to narrow the union type, we can infer exactly what type the object returned is. This creates what's known as a discriminated union, giving us type safety without brittle type guards.

Our query will now look something like this:

mutation signUp($input: SignUpInput!) {
  signUp(input: $input) {
    __typename
    ... on User {
      id
      email
      name
    }
    ... on ValidationError {
      field
      message
    }
  }
}

And our app can easily reference the fields it needs in a type-safe manner:

const [signUp, { data, error, loading }] = useMutation(signUpMutation)

if( error ) {
  // handle unexpected error
}

const onSubmit = async (formData: FormData) => {
  await signUp({
    variables: {
      input: {
        email: formData.email,
        password: formData.password,
        name: formData.name,
      }
    }
  });
}

if( data.signUp.__typename === 'ValidationError' ) {
  // TypeScript knows field and message are available 
  // because the type is inferred as typeof ValidationError
  setError(data.signUp.field, data.signUp.message); 
} else if( data.signUp.__typename === 'User' ) {
  // handle successful sign up, e.g., redirect to a welcome page
}

We are now able to maintain the benefit of our GraphQL by utilising its schema to know exactly what fields we are getting back as well as type safety from inferred types from the __typename field.

To summarise: top-level errors for unexpected errors; data as errors when the information the errors provide is relevant to the end-user experience; use __typename as a differentiator between your unions.

Field-Level Resolvers: The Key to Consistent and Resilient GraphQL APIs

Andrew McCallum — Wed, 04 Dec 2024 17:19:18 +0000

GraphQL has revolutionised how we fetch and shape data, providing a clean abstraction layer between clients and servers. One of its core features, resolvers, allows us to define how each field in our schema gets its data. In some cases, developers may unintentionally diminish the benefits of GraphQL by relying on utility methods in resolvers. This practice not only defeats the purpose of GraphQL's design but also introduces unnecessary complexity and potential bugs.

Let’s dive into why this is problematic, how to do better, and how to improve error handling with field-level resolvers.

The Power of Resolvers

In GraphQL, resolvers are invoked for every instance of a type, regardless of where that type appears in your schema. This abstraction ensures that the logic for resolving data stays consistent across the board. For example:

schema {
  query: Query
}

type Query {
  project(id: ID!): Project
  user(id: ID!): User
}

type Project {
  id: ID!
  name: String!
  owner: User!
}

type User {
  id: ID!
  name: String!
  email: String!
}

Here, the User type is used in two places: directly in the Query for fetching users and nested within the Project type as the owner. Thanks to GraphQL's resolver system, we can define a single User resolver to handle how User fields are resolved, ensuring consistent behaviour everywhere User appears.

The Problem with `utils`

When you introduce utility methods to shape data outside of your resolvers, you break this abstraction. Consider this example:

// utils.ts
function mapToUser(userData: User) {
  return {
    id: userData.id,
    name: userData.full_name,
    email: userData.contact_email,
  };
}

// resolvers.ts
const resolvers: Resolvers<Context> = {
  Query: {
    project: async (_, { id }, { dataSources }) => {
      const project = await dataSources.projectAPI.getProject(id);
      return {
        ...project,
        owner: mapToUser(project.owner), // Utility method called here
      };
    },
    user: async (_, { id }, { dataSources }) => {
      const user = await dataSources.userAPI.getUser(id);
      return mapToUser(user); // Utility method called here
    },
  },
};

At first glance, this might seem fine. But here’s why it’s problematic:

1. Duplicated Logic

You’re forced to call mapToUser in every resolver where a User type appears. Forgetting to call it or calling it incorrectly can lead to inconsistent behavior across your API.

2. Breaking Abstraction

GraphQL's resolver system is designed to centralize how each type is resolved. By using a utility method, you’re sidestepping this feature and making your code less intuitive.

3. Loss of Flexibility

If you ever need to modify how a User type is resolved (e.g., adding new fields or handling errors), you’ll have to hunt down every place where mapToUser is called instead of updating a single resolver.

The Better Approach: Leverage Type Resolvers

Instead of using utility methods, define resolvers for your GraphQL types. Here’s how you can rewrite the above example:

const resolvers: Resolvers<Context> = {
  Query: {
    project: async (_, { id }, { dataSources }) => {
      return dataSources.projectAPI.getProject(id);
    },
    user: async (_, { id }, { dataSources }) => {
      return dataSources.userAPI.getUser(id);
    },
  },
  User: {
    id: (user) => user.id,
    name: (user) => user.full_name,
    email: (user) => user.contact_email,
  },
  Project: {
    owner: (project, _, { dataSources }) => {
      return dataSources.userAPI.getUser(project.ownerId);
    },
  },
};

Why This is Better

Consistency: The User resolver ensures that all User instances are resolved the same way, no matter where they appear in the schema.
Centralized Logic: Changes to how a User is resolved only need to be made in one place.
Harnessing GraphQL’s Strengths: By embracing the resolver system, you’re aligning with GraphQL’s core design principles and leveraging its full potential.

Enhanced Error Handling with Field-Level Resolvers

Another benefit of splitting logic into field-level resolvers is improved error handling. If you rely on a single resolver for an entire object, any error will propagate to the entire object, making all its fields unavailable. Field-level resolvers mitigate this by isolating errors to specific fields, allowing other data to still be returned.

Example: Single Object Resolver with Errors

Query: {
  project: async (_, { id }, { dataSources }) => {
    const project = await dataSources.projectAPI.getProject(id);

    return {
        id: project.id,
        title: project.title,
        owner: await dataSources.userAPI.getProjectOwner(project.owner.id) // async call that could error
  },
}

If getProjectOwner() fails, the client receives no data for project, even if some fields could have been resolved independently.

Example: Field-Level Resolvers for Better Resilience

Query: {
  project: async (_, { id }, { dataSources }) => {
    return dataSources.projectAPI.getProject(id);
  }
},
Project: {
  owner: async (project) => {
    return dataSources.userAPI.getProjectOwner(project.owner.id) // async call that could error
  }
}

In this case:

If getProjectOwner() fails, GraphQL can still resolve other parts of the query if they don’t depend on project.
Errors are isolated to specific fields, making it easier to debug and allowing partial data to be returned to the client.

Benefits of Field-Level Resolvers for Error Handling

Graceful Degradation: If one field fails to resolve, other fields can still return data.
Enhanced Debugging: Errors are isolated to specific fields, making them easier to trace.
Improved Resilience: Clients receive as much data as possible, even if some parts fail.

Considerations

While field-level resolvers improve error handling, they may introduce performance overhead if each field fetches its data separately. Tools like DataLoader can batch and cache requests to optimise performance.

Conclusion

Using utility methods in your resolvers may seem like a shortcut, but it ultimately undermines the power and elegance of GraphQL. By defining resolvers for your types and leveraging field-level resolvers, you can maintain a clean, consistent, and scalable API while improving error resilience. Embrace the abstraction that GraphQL provides—your future self and your users will thank you!

The Importance of Avoiding Code Style Divergence and 3 Tips to Ensure Consistency

Andrew McCallum — Tue, 25 Jul 2023 10:24:24 +0000

In the dynamic world of software development, teams collaborate to create complex, innovative solutions. However, amidst this creativity, a subtle yet potent problem can emerge - Code Style Divergence. When each developer follows their own coding patterns and conventions, the codebase can become a chaotic jumble of inconsistent styles, hindering productivity, and maintainability. In this blog post, we'll explore the significance of avoiding Code Style Divergence and present three practical tips to promote consistency within your development team.

Why Consistency Matters:

Consistency is the bedrock of successful software development teams. While individual creativity is important, a harmonious coding style is essential for several reasons:

Readability and Maintainability: A consistent codebase is easier to read, understand, and maintain. Developers can quickly grasp the logic behind the code, leading to quicker debugging and enhancements.

Collaboration: When team members follow the same conventions, collaborating on projects becomes a seamless process. It fosters effective communication, leading to fewer misunderstandings and conflicts during code integration.

Reduced Technical Debt: Consistent code practices reduce technical debt. With clear guidelines, refactoring and improving code becomes more efficient, saving time and effort in the long run.

Onboarding New Team Members: New team members can onboard more smoothly when they encounter a codebase with a well-defined style. They'll spend less time learning the code structure and more time contributing to the project.

Three Tips to Avoid Code Style Divergence:

1. Embrace Frameworks and Libraries with Enforced Patterns:

Using frameworks and libraries that enforce a specific coding pattern can be a game-changer. These tools come with built-in conventions, guiding developers to follow a consistent approach. For example, when building web applications in React, adopting popular libraries like Material-UI can streamline the user interface design process and ensure a unified look and feel.

2. Champion "Convention over Configuration":

Adopting a "Convention over Configuration" (CoC) approach can be pivotal in promoting consistency. Instead of leaving every aspect of the code to individual preferences, establish a set of shared conventions. Decide on key aspects such as naming conventions, indentation, and documentation style. A well-documented style guide can be the team's North Star, guiding them towards uniformity.

3. Leverage Automated Tools and Code Reviews:

Automated tools and code reviews form a powerful duo in the fight against Code Style Divergence. Incorporate linting tools like ESLint, Pylint, or RuboCop into your development pipeline to automatically detect and flag style violations. Integrate these checks into your Continuous Integration/Continuous Deployment (CI/CD) process to ensure every code change aligns with the established conventions.

Additionally, conduct regular code reviews where team members meticulously review each other's code for style adherence. Encourage constructive feedback during these reviews to maintain a collaborative environment.

Consistency is the cornerstone of successful software development teams. Avoiding Code Style Divergence ensures a harmonious, maintainable, and efficient codebase. By embracing frameworks, enforcing conventions, and leveraging automated tools and code reviews, your team can foster a culture of consistent coding practices and pave the way for future successes. So, remember, when it comes to code style, unity is strength!

Taking Feature Flags to the Next Level: Simplified Feature Flags and Dynamic Overrides

Andrew McCallum — Tue, 18 Jul 2023 07:07:53 +0000

As developers, we know the importance of feature flags in modern web applications. They allow us to control the release and activation of features with ease, enabling smooth experimentation and testing. Today, we are thrilled to introduce use-feature, a powerful React NPM package designed to streamline the process of managing feature flags within your React applications.

What is use-feature?

use-feature is a versatile React hook that simplifies the implementation of feature flags in your React apps. With support for all the main React frameworks, including Gatsby, Next, Vite, and Create-react-app, integrating feature flags has never been more accessible.

Why Use use-feature?

Flexibility and Customisation: use-feature is designed with flexibility in mind. It allows you to set feature flags using a boolean variable or look for environment variables in your .env files. This means you can configure feature flags based on different conditions, tailoring the behaviour to suit your specific use cases.
Dynamic Overrides: One of the standout features of use-feature is its ability to be dynamically overridden. This means you can enable or disable a feature on the fly using query strings, cookies, or local storage. It's particularly useful when you want to have a feature disabled in production but enable it temporarily for specific users or for yourself during development and testing.
Seamless Integration: Integrating use-feature into your existing React projects is a breeze. With just a few lines of code, you can effortlessly add feature flags to control various aspects of your application.

Getting Started

To get started with use-feature, simply install it via NPM using the following command:

npm install use-feature

Set your feature flag value in your .env file:

cool_feature=true

Next, import the hook into your React component:

import { useFeature } from 'use-feature';

Now, let's see how easy it is to create a feature flag:

function MyComponent() {
  const isCoolFeatureEnabled = useFeature('cool_feature', false);

  // Rest of your component logic
}

In this example, the useFeature hook takes two arguments: the feature flag name ('cool_feature') and the default value (false). The hook operates in the following way: First, it checks if there is an environment variable set with the name cool_feature. If such an environment variable exists, it will use its value as the feature flag. Next, the hook checks for any possible overrides for the feature flag, which could be provided through the query string, cookie, or local storage. If an override value is available, it will be used. However, if no override is found, the hook will fall back to using the default value provided. This ensures a seamless and flexible way to handle feature flags in your React application.

Let's take a look at some real-world scenarios where use-feature can be incredibly valuable:

Beta Testing: You can use use-feature to activate beta features for selected users by setting up an override through query parameters. This allows you to gather feedback and fine-tune features before a full release.
A/B Testing: Run A/B tests with ease by enabling or disabling specific features for different users, directly from the query string or cookies.
Internal Development: Keep a feature hidden from users but enable it for developers and testers to facilitate development and debugging.

Feature flags are essential for delivering flexible and well-tested web applications. With use-feature, you can easily manage feature flags in your React apps and even override them dynamically when needed. Its seamless integration and versatility make it a must-have tool for any React developer.

Start using use-feature today by installing the package via NPM and explore its capabilities to optimise your React app development process. For more information and detailed examples, check out the GitHub repository at https://github.com/feijoa-dev/use-feature.

We look forward to seeing the innovative ways you implement feature flags with use-feature in your React applications! Happy coding!

A Step-by-Step Guide for Deploying a Node.js GraphQL Server to AWS Lambda with GitHub Actions and Terraform

Andrew McCallum — Thu, 13 Jul 2023 12:55:59 +0000

Deploying a Node.js GraphQL server to AWS Lambda offers numerous advantages, including scalability, cost efficiency, and simplified management. In this step-by-step guide, we'll walk you through the process of setting up a deployment pipeline for your Node.js GraphQL server using GitHub Actions for continuous integration and Terraform for AWS infrastructure management. By the end, you'll have a streamlined workflow for deploying your server to AWS Lambda with ease, using the NodeJS.

Prerequisites:
Before we begin, ensure you have the following prerequisites in place:

A Node.js GraphQL server: Prepare your Node.js GraphQL server code, ensuring it is functional and ready for deployment.
AWS Account: Sign up for an AWS account if you don't have one already.
GitHub Account: Ensure you have a GitHub account to utilize GitHub Actions.
Basic knowledge of Git and GitHub: Familiarize yourself with version control and basic Git operations.
Terraform Installed: Install Terraform on your local machine (https://www.terraform.io/downloads.html).

Step 1: Set up AWS Lambda and API Gateway using Terraform:
To begin, we'll use Terraform to provision the necessary AWS resources. Create a new directory and follow these steps:

Initialize Terraform in your project directory using the command: terraform init.
Create a new file named main.tf and define the AWS resources required for Lambda and API Gateway. Here's a sample configuration:

provider "aws" {
  region = "us-east-1"  # Replace with your desired AWS region
}

resource "aws_lambda_function" "graphql_server" {
  function_name = "my-graphql-server"
  runtime = "nodejs18.x"
  handler = "index.handler"
  memory_size = 512
  timeout = 10

  # Add other necessary configurations, such as VPC settings or environment variables.
}

resource "aws_api_gateway_rest_api" "graphql_api" {
  name = "my-graphql-api"
  endpoint_configuration {
    types = ["REGIONAL"]
  }
}

resource "aws_api_gateway_resource" "graphql_resource" {
  rest_api_id = aws_api_gateway_rest_api.graphql_api.id
  parent_id = aws_api_gateway_rest_api.graphql_api.root_resource_id
  path_part = "graphql"
}

resource "aws_api_gateway_method" "graphql_method" {
  rest_api_id = aws_api_gateway_rest_api.graphql_api.id
  resource_id = aws_api_gateway_resource.graphql_resource.id
  http_method = "POST"
  authorization = "NONE"
}

resource "aws_api_gateway_integration" "graphql_integration" {
  rest_api_id = aws_api_gateway_rest_api.graphql_api.id
  resource_id = aws_api_gateway_resource.graphql_resource.id
  http_method = aws_api_gateway_method.graphql_method.http_method
  integration_http_method = "POST"
  type = "AWS_PROXY"
  uri = aws_lambda_function.graphql_server.invoke_arn
}

resource "aws_lambda_permission" "graphql_permission" {
  statement_id = "AllowAPIGatewayInvoke"
  action = "lambda:InvokeFunction"
  function_name = aws_lambda_function.graphql_server.function_name
  principal = "apigateway.amazonaws.com"
  source_arn = aws_api_gateway_rest_api.graphql_api.execution_arn
}

Customize the configuration to suit your requirements, such as function name, region, or additional environment variables.
Apply the Terraform configuration by running: terraform apply.
Terraform will provision the Lambda function, API Gateway, and necessary permissions.

Step 2: Configure GitHub Actions for Continuous Deployment:
GitHub Actions allow you to automate the deployment process. Follow these steps to create a deployment workflow:

Create a new file named .github/workflows/deploy.yml in your GitHub repository.
Define the deployment workflow using the following code snippet:

name: Deploy to AWS Lambda

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Deploy to AWS Lambda
        uses: appleboy/lambda-action@v0.5.0
        with:
          aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          region: us-east-1  # Replace with your desired AWS region
          function_name: my-graphql-server
          zip_file: index.js

The workflow is triggered whenever changes are pushed to the main branch.
Ensure you have the AWS access keys stored as secrets in your GitHub repository settings.
Customize the region and function name in the workflow file to match your setup. Step 3: Update your Node.js GraphQL Server code: To ensure your GraphQL server works correctly in the Lambda environment, make a few adjustments:

Modify your server code (e.g., index.js) to export a handler function. Here's an example:

const { ApolloServer, gql } = require('apollo-server-lambda');

const typeDefs = gql`
  type Query {
    hello: String
  }
`;

const resolvers = {
  Query: {
    hello: () => 'Hello, World!',
  },
};

const server = new ApolloServer({
  typeDefs,
  resolvers,
});

exports.handler = server.createHandler();

Ensure you have the necessary dependencies (e.g., apollo-server-lambda) in your package.json file.

Step 4: Commit and Deploy:
Commit your changes to the GitHub repository, and the deployment workflow will automatically trigger. The GitHub Actions workflow will build your project, create a deployment package, and deploy it to AWS Lambda.

Congratulations! You have successfully set up a deployment pipeline for your Node.js GraphQL server using GitHub Actions and Terraform. You now have an automated process for deploying your server to AWS Lambda. This streamlined workflow will save you time and effort, allowing you to focus more on developing your application. Experiment with different features and configurations to further optimize your deployment process. Happy coding and deploying!

A Step-by-Step Guide to Building a Custom Tooltip in React using useRef and Hooks

Andrew McCallum — Tue, 11 Jul 2023 16:58:29 +0000

In this blog post, I will guide you through the process of creating a reusable and extensible tooltip component using the useRef hook and custom hooks. By following along, you will not only gain a deeper understanding of how the useRef hook functions, but also learn how to implement your own hooks. It's an excellent opportunity to enhance your knowledge and skills in React development.

If you want to follow along, you may want to use https://codesandbox.io and I'd start by creating the following file structure. Otherwise, keep reading and find a working example at the end.

├── src
│   ├── App.tsx
│   ├── Tooltip.tsx
│   ├── Tooltip.hooks.tsx
│   ├── Tooltip.css

Firstly, we are going to create our Tooltip component. This will be a simple component that just renders its children. It will also receive an elementRef as a prop that will come in handy later.

// Tooltip.tsx
import React, { FC, RefObject } from "react";

type TooltipProps = {
  elementRef: RefObject<HTMLElement>;
  children: React.ReactNode;
};

const Tooltip: FC<TooltipProps> = ({ children, elementRef }) => {
  return <div>{children}</div>;
};

export default Tooltip;

In our App.tsx, we are now going to render a button to which we attach a ref. We also render our Tooltip component and pass our button ref into it.

// App.tsx
import React, { useRef } from "react";
import Tooltip from "./Tooltip";

export default function App() {
  const buttonRef = useRef<HTMLButtonElement>(null);

  return (
    <>
      <Tooltip elementRef={buttonRef}>
        <span>I'm a tooltip</span>
      </Tooltip>
      <div className="App">
        <button className="button" ref={buttonRef}>
          Hello world
        </button>
      </div>
    </>
  );
}

Now we are going to create our custom hook. This hook will contain the logic for making the tooltip visible and positioning it on the screen.

// Tooltip.hooks.tsx
import { useState } from "react";

type Position = {
  top?: number;
  left?: number;
  width?: number;
};

export function useTooltip() {
  const [isVisible, setIsVisible] = useState<boolean>(false);
  const [position, setPosition] = useState<Position>({});

  return {
    position: {
      top: position.top ?? 0,
      left: position.left ?? 0,
      width: position.width ?? 0,
    },
    isVisible,
  };
}

Let's now use our useTooltip hook in our Tooltip component. If our tooltip is not visible, we'll return nothing, and we will make sure we pass the top and left positions into our div's inline styles. We need to use inline styles here because the values are dynamic, so we don't want to hardcode them in our CSS file.

// Tooltip.tsx
import React, { FC, RefObject } from "react";
import { useTooltip } from "./Tooltip.hooks";
import "./Tooltip.css"; // importing our styles here

type TooltipProps = {
  elementRef: RefObject<HTMLElement>;
  children: React.ReactNode;
};

const Tooltip: FC<TooltipProps> = ({ children, elementRef }) => {
  const { position, isVisible } = useTooltip();

  if (!isVisible) {
    return null;
  }

  return (
    <div
      className="tooltip-container" // adding className here for later use
      style={{
        top: position.top,
        left: position.left,
      }}
    >
      {children}
    </div>
  );
};

export default Tooltip;

We want the useTooltip hook to have some context about the element we are hovering over, so we are going to pass our button ref from the Tooltip component into the hook. While we're here, we are also going to add a couple of functions that will be used when the user hovers over our button. These are onMouseEnter for when the cursor hovers over the element, and onMouseLeave for when the cursor exits the hover. When these events occur, we will set our tooltip to visible.

// Tooltip.hooks.tsx
import { useState, RefObject, useCallback, useEffect } from "react";

type Position = {
  top?: number;
  left?: number;
  width?: number;
};

type UseTooltipProps = {
  ref: RefObject<HTMLElement>;
};

export function useTooltip({ ref }: UseTooltipProps) {
  const [isVisible, setIsVisible] = useState<boolean>(false);
  const [position, setPosition] = useState<Position>({});

  useEffect(() => {
    if (!ref.current) {
      return;
    }

    if (isVisible) {
      const { left, width, bottom } = ref.current.getBoundingClientRect();
      setPosition({
        top: bottom,
        left: left,
        width,
      });
    }

    if (!isVisible) {
      setPosition({});
    }
  }, [isVisible, ref]);

  const onMouseEnter = useCallback(() => {
    setIsVisible(true);
  }, []);

  const onMouseLeave = useCallback(() => {
    setIsVisible(false);
  }, []);

  return {
    position: {
      top: position.top ?? 0,
      left: position.left ?? 0,
      width: position.width ?? 0,
    },
    isVisible,
    onMouseEnter,
    onMouseLeave,
  };
}

As you can see, we have defined two new functions: onMouseEnter and onMouseLeave, which we define using useCallback. This allows us to cache the function definition between re-renders and ensures that whenever we set our position or isVisible values, the functions don't get redefined, avoiding unnecessary renders that can result in a flashing component.

In our onMouseEnter function, we set isVisible to true so that the Tooltip is actually rendered, and in our onMouseLeave function, we set it to false.

You may also notice that we are setting the position of our tooltip in a useEffect that gets called whenever isVisible changes. This will make sense later, but essentially, we only want to set our tooltip's position once it has rendered because we are going to need to calculate its dimensions to position it correctly.

For now, we are aligning the left side of our button with the left side of our tooltip and the top of our tooltip with the bottom of our button. We will improve this shortly.

Now we can update our Tooltip component to pass our button ref and attach the onMouseEnter / onMouseLeave events to it.

// Tooltip.tsx
import React, { FC, RefObject, useEffect } from "react";
import { useTooltip } from "./Tooltip.hooks";
import "./Tooltip.css";

type TooltipProps = {
  elementRef: RefObject<HTMLElement>;
  children: React.ReactNode;
};

const Tooltip: FC<TooltipProps> = ({ children, elementRef }) => {
  const tooltipRef = useRef<HTMLDivElement>(null);

  const {
    position,
    isVisible,
    onMouseEnter,
    onMouseLeave,
  } = useTooltip({
    ref: elementRef,
    tooltipRef,
  });

  useEffect(() => {
    const element = elementRef?.current;

    if (element) {
      element.addEventListener("mouseenter", onMouseEnter);
      element.addEventListener("mouseleave", onMouseLeave);
    }

    // cleans up event listeners by removing them when the component is unmounted
    return () => {
      if (element) {
        element.removeEventListener("mouseenter", onMouseEnter);
        element.removeEventListener("mouseleave", onMouseLeave);
      }
    };
  }, [elementRef, onMouseEnter, onMouseLeave]);

  if (!isVisible) {
    return null;
  }

  return (
    <div
      ref={tooltipRef}
      className="tooltip-container" // adding className here for later use
      style={{
        top: position.top,
        left: position.left,
      }}
    >
      {children}
    </div>
  );
};

export default Tooltip;

If we add some CSS to our Tooltip, we should be able to start seeing this come together.

/* Tooltip.css */

.tooltip-container {
  position: absolute;
  font-size: 14px;
  line-height: 20px;
  background-color: #2c3a43;
  color: white;
  padding: 16px;
  margin: 0;
}

.tooltip-container::before {
  content: "";
  position: absolute;
  top: -12px;
  left: 50%;
  transform: translateX(-50%);
  width: 0;
  height: 0;
  border-left: 16px solid transparent;
  border-right: 16px solid transparent;
  border-bottom: 18px solid #2c3a43;
}

You'll notice the tooltip isn't positioned where we want it, so let's go ahead and fix its position.

We're going to update the onMouseEnter function to do some simple math. We want our tooltip to be pointing to the middle of our button, so we need to align the middle of our tooltip div with the middle of the button element. To do this, our useTooltip hook needs to be aware of the Tooltip's div element and be able to get some dimensions from it.

We get the dimensions of the tooltip within a useEffect because that ensures the isVisible is set to true. That way the element has actually rendered and has a width set. Otherwise, if the element has not rendered, it would have a width of zero and we wouldn't be able to calculate the middle point.

Next we will align our tooltip below our button by providing a verticalOffset

// Tooltip.hooks.tsx
import React, { RefObject, useCallback, useEffect, useState } from "react";

type UseTooltipProps = {
  ref: RefObject<HTMLElement>;
  tooltipRef: RefObject<HTMLDivElement>;
};

type Position = {
  top?: number;
  left?: number;
  width?: number;
};

export function useTooltip({ ref, tooltipRef }: UseTooltipProps) {
  const [isVisible, setIsVisible] = useState<boolean>(false);
  const [position, setPosition] = useState<Position>({});

  useEffect(() => {
    if (!ref.current) {
      return;
    }

    if (isVisible) {

      const { left, width, bottom } = ref.current.getBoundingClientRect();

      const tooltipWidth = tooltipRef?.current?.getBoundingClientRect().width || 0;

      const middle = left + width / 2 - tooltipWidth / 2;

      const verticalOffset = 12 // If you change the size of the arrow in the css class tooltip-container::before then you will need to change this value

      setPosition({
        top: bottom + verticalOffset,
        left: middle,
        width,
      });
    }

    if (!isVisible) {
      setPosition({});
    }
  }, [isVisible, ref, tooltipRef]);

  const onMouseEnter = useCallback(() => {
    setIsVisible(true);
  }, []);

  const onMouseLeave = useCallback(() => {
    setIsVisible(false);
  }, []);

  return {
    position: {
      top: position.top ?? 0,
      left: position.left ?? 0,
      width: position.width ?? 0,
    },
    isVisible,
    onMouseEnter,
    onMouseLeave,
  };
}

Finally, we can update our Tooltip component to create a ref for our Tooltip div and pass it to our hook so that the aforementioned calculations can be done.

// Tooltip.tsx
import React, { FC, RefObject, useEffect, useRef } from "react";
import { useTooltip } from "./Tooltip.hooks";
import "./Tooltip.css";

type TooltipProps = {
  elementRef: RefObject<HTMLElement>;
  children: React.ReactNode;
};

const Tooltip: FC<TooltipProps> = ({ children, elementRef }) => {
  const tooltipRef = useRef<HTMLDivElement>(null);

  const {
    position,
    isVisible,
    onMouseEnter,
    onMouseLeave,
  } = useTooltip({
    ref: elementRef,
    tooltipRef,
  });

  useEffect(() => {
    const element = elementRef?.current;

    if (element) {
      element.addEventListener("mouseenter", onMouseEnter);
      element.addEventListener("mouseleave", onMouseLeave);
    }

    // cleans up event listeners by removing them when the component is unmounted
    return () => {
      if (element) {
        element.removeEventListener("mouseenter", onMouseEnter);
        element.removeEventListener("mouseleave", onMouseLeave);
      }
    };
  }, [elementRef, onMouseEnter, onMouseLeave]);

  if (!isVisible) {
    return null;
  }

  return (
    <div
      ref={tooltipRef}
      className="tooltip-container" // adding className here for later use
      style={{
        top: position.top,
        left: position.left,
      }}
    >
      {children}
    </div>
  );
};

export default Tooltip;

There we have it! Our tooltip should now display below our button when we hover over it.

One thing that makes this component highly extensible is the method we use to pass the tooltip content as children. While many components only accept a text prop, we enable users to send a React node, granting them the ability to render any component with their preferred styles. However, a potential downside of this approach, especially in a design system context, is the need to maintain consistency with the intended designs. In such cases, it may be advisable to provide some level of prescription regarding how the tooltip content should be rendered.

In conclusion, we have learned how to create a versatile and reusable tooltip component using React, useRef, and custom hooks. By leveraging useRef, we were able to create a tooltip that can be attached to any element on the screen. The use of custom hooks allowed us to handle the tooltip's visibility and positioning logic in a clean and reusable manner. With the flexibility of passing React nodes as tooltip content, we can customise the appearance and behaviour of our tooltips to suit our specific needs.

Checkout the working version here

How to Scale your WebSocket Server with DynamoDB and SNS.

Andrew McCallum — Sun, 05 Mar 2023 10:16:50 +0000

Scaling WebSockets can be a challenging task. Although there are different approaches to handle this, we will explore how to horizontally scale using AWS SNS to broadcast events across instances. This ensures that all clients receive the appropriate broadcast.

One of the main difficulties in horizontally scaling services is that if you have multiple instances of your WebSocket server running, there is a risk of users joining different servers. This is not an issue if these users do not need to be aware of each other's actions. However, as soon as multiple users need to receive each other's messages, things can become complicated.

Let’s take a chatroom as an example. Given a client sends a message to the WebSocket server, then I want all users in that room to send and receive messages to each other. Now imagine I have two instances of my WebSocket server running. John joins server one and his friend Lucy joins server two. When John sends a message “Hello world” he wants this broadcast to his friend Lucy, but because she is connected to a different server, she doesn’t receive the message. Only users on server one will have that message broadcast to them.

One way to get around this is to utilise a message service to notify all socket servers that there has been a message received. We can use AWS SNS as a messaging service here. Even better, we can trigger AWS SNS whenever there is an update to DynamoDB. Below is a diagram of how this might look.

In the above diagram, we can see we have two clients (John and Lucy) connecting to different WebSocket servers. The WebSocket server will receive a message such as “Hello World” and then send that to our EC2 instance which will then write the message to our DynamoDB. Our DynamoDB will then stream the updated data into a Lambda function that will publish a message to our SNS service. The SNS service will then publish a message to any service that is subscribed to that topic, in our case it will be our two WebSocket services.

Each of our WebSocket service will receive a message that says John sent a message “Hello World” and will be able to emit this back out to any client that is connected to that instance. This means Lucy will receive the message "Hello world" from John even though she is on a different server.

The great thing about doing it this way is that we can easily scale our WebSocket servers horizontally without worrying about users being connected to a different instance of the server. As long as all of our WebSocket servers are subscribed to the same SNS topic, they will receive all of the broadcasted messages, regardless of which instance of the server the users are connected to. This allows us to add or remove WebSocket servers as needed to handle changes in load, without having to worry about users being disconnected or messages being missed.

Scalability is a major concern for any WebSocket server application. By leveraging AWS services like DynamoDB and SNS, we can easily horizontally scale our WebSocket servers without worrying about users being connected to different instances of the server. Using SNS to broadcast events across instances ensures that all clients receive the appropriate broadcast and that users are not disconnected or messages missed. With this approach, we can add or remove WebSocket servers as needed to handle changes in load, making our WebSocket server application highly scalable.

Is React Testing Library a Suitable Replacement for Enzyme?

Andrew McCallum — Fri, 17 Dec 2021 18:12:25 +0000

React Testing Library has absolutely exploded onto the scene in the last few years and seems to have knocked other testing libraries off their perch as number one. So, is React Testing Library a good replacement for Enzyme? Well, let's dive into what these libraries are and how they can compliment your overall testing strategy.

Developed by Kent C. Dodds, React Testing Library describes itself as a set of "simple and complete testing utilities that encourage good testing practices". It aims to make tests more maintainable by discouraging testing of implementation detail.

One way React Testing Library discourages this is by not allowing tests to get access to the props or state of a component. The API instead has methods such as getByText and getByRole which are used to get HTML elements on the rendered screen. This makes the tests interact with the app in a similar way to how a user might.

On the contrary, Enzyme allows for a more unit test-like approach. Enzyme's affordance to shallow render means you can test individual components. As well as being able to access props and state within the test, it also allows testing of implimentation details. It can be argued that these kinds of unit tests act as a form of documentation as to how a component should operate.

There are both arguments for and against this kind of testing and I think both approaches have got their places. I am not here to tell you which is better as I believe that depends on the project itself.

React Testing Library is more behavioural focused and it only allows deep rendering. This suggests it positions itself as an integration testing framework. In contrast, Enzyme's ability to shallow render as well as test implimentation suggests it is positioned as a unit test framework. So where do these libraries fit into your testing strategy?

Regardless of whether you subscribe to the testing pyramid or dorito strategy, we can all agree that having a range of unit, integration and end-to-end (E2E) tests is a good idea. So, let's look at how some of these frameworks might compliment each other in various strategies.

React Testing Library focus

As you can see here above, these strategies use Jest for running unit tests, React Testing Library for integration and Cypress for E2E. This approach does not include a library that allows testing components individually, making it is difficult to get good unit test coverage. Jest will only really allow unit testing of utility functions which is only going to be a small percentage of your application. Therefore, it would be wise to place more importance on your integration and E2E tests. If this is your focus, a dorito strategy would be the better approach.

Enzyme focus

This approach utilises Enzyme's ability to be used for both unit and integration tests. Similarly, Cypress overlaps the boundaries of integration and E2E testing.

With Enzyme's affordance to gain greater unit test coverage, it would be prudent to use a testing pyramid strategy. Being able to quickly write unit tests, as well as execute them quickly means you can have a lot of them.

Enzyme & React Testing Library

Lastly, let's consider a mix. Using Enzyme for unit, React Testing Library for integration and Cypress for E2E. Whilst technically this can be done, you may find React Testing Library becomes supurflous due to Enzyme's and Cypress's ability to also cover integration testing. This approach also comes with the additional effort of having to maintain more dependencies.

In summary, React Testing Library is not a straight replacement for Enzyme. One is more focused on unit testing and the other on integration testing. They both have their own strengths in different parts of the testing hierarchy. Perhaps the question is not, "which testing library should I use?" but instead "which testing strategy should I use?".

Deploy your Node App to EC2 with Github Actions

Andrew McCallum — Fri, 10 Dec 2021 18:00:30 +0000

In this post we are going to run through how to deploy our code to AWS EC2 via Github Actions. This will include the following steps:

Create EC2 instance
Configure IP and domain name
SSH into our server
Install NGINX
Install Node and PM2
Deploy with Github Actions

Create EC2 instance

We are going to need to launch a new instance, create an SSH key pair and configure the correct security groups.

I wont bore you with the detail of going through the AWS EC2 creation wizard but you can go ahead and create a new EC2 instance with an Ubuntu machine image with a t2 micro and download your new keys.

Make sure you download your ssh keys and store them somewhere secure as you will need them again later.

We have created our new instance so whilst it is booting up, we are going to configure a security group. This will allow us to accept incoming and outgoing network reqeusts on specific ports and IP addresses.

Go to the Security Groups page and then select "Create security group".

We are going to allow HTTP (port 80) and HTTPS (port 443) on both our incoming and outgoing connections. This means we can access our app via http or https and we can call API's from our app on both those protocols too. Keep in mind ssh (port 22) is enabled by default.

If your app is connecting to a database, you may want to allow rules for PostgreSQL or MySQL etc.

Configure IP and domain name

Here we will assign an IP address to our EC2 instance and then update our domain's name server to point the domain name to our new IP.

Within the EC2 service section of AWS, navigate to Elastic IPs. Here we can click "Allocate Elastic IP address" to generate a new IP address. We can now assign that to the newly created EC2 instance we just created by clicking actions > Associate elastic IP address and selecting our EC2 instance.

Next we will point our domain name to our new IP address. In my case, my domain name uses AWS Route53 as a name server so I will navigate there and create an A record to point <my_ip_address> -> www.my-website.com.

SSH into our server

Next up we are going to access our EC2 instance via SSH. In oder to do this, we will do the following:

Open an SSH client.
Locate your private key file
Run this command, if necessary, to ensure your key is not publicly viewable.
```
$ chmod 400 My-ssh-key.pem
```

Connect to your instance using its Public DNS:

$ ssh -i "My-ssh-key.pem" ubuntu@<host>.compute.amazonaws.com

You should now have SSH access to your EC2 server.

Install NGINX

After ssh'ing into our server, we will need to do the following; install NGINX, configure firewall, forward web traffic ports and lastly set directory permissions.

$ sudo apt update
$ sudo apt install nginx

We are then going to adjust our firewall to allow http and https connections to our NGINX server.

$ sudo ufw allow 'Nginx Full'

We should then have an active web server:

$ systemctl status nginx

If we visit http://<my_ip_address> we should see the NGINX welcome page.

We now know our web server is accepting connections on port 80. Our Node app is going to be running on port 3000 so we are going to need to forward connections from port 80 to 3000. This will be done via our NGINX config in the sites-available file.

$ sudo nano /etc/nginx/sites-available/my-app

We are going to paste in this config:

upstream my_nodejs_upstream {
    server 127.0.0.1:3000;
    keepalive 64;
}

server {
    listen 80;
    # listen 443 ssl;

    server_name www.my-website.com; # This is the domain name we set up earlier to point to our IP address
    # ssl_certificate_key /etc/ssl/main.key;
    # ssl_certificate     /etc/ssl/main.crt;

    location / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $http_host;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_pass http://my_nodejs_upstream/;
        proxy_redirect off;
        proxy_read_timeout 240s;
    }
}

This listens for traffic for www.my-website.com (this will be the domain you set up earlier to point to your IP address) on port 80 and forwards it to our node app on port 3000. As you can see, I have commented out the SSL config but if you have an SSL cert, feel free to use that instead.

We are now going to need to symlink this file into sites-enabled directory.

$ sudo ln -s /etc/nginx/sites-available/my-app /etc/nginx/sites-enabled

We can go ahead and restart NGINX to make all these changes take effect.

$ sudo systemctl restart nginx

Lastly for this step, we are going to create a file for our application files to live in and set the correct permissions.

$ sudo mkdir /var/www/my-app

Change the directory owner and group:

$ sudo chown www-data:www-data /var/www/my-app

Allow the group to write to the directory with appropriate permissions:

$ sudo chmod -R 775 /var/www

Add myself to the www-data group:

$ sudo usermod -a -G www-data [my username]

We should now have NGINX installed with a config that forwards incoming requests on port 80 to port 3000 and have a directory created to contain our site files with all the correct permissions.

Install Node and PM2

We are going to install Node via NVM so that we can easily change node versions and then we will use npm to install pm2.

To install nvm:

$ curl https://raw.githubusercontent.com/creationix/nvm/master/install.sh | bash 
$ source ~/.profile

Install the version of Node you want
```
$ nvm install 14
```
We should now have Node and NPM installed which we can now use to install PM2.
```
$ npm install pm2 -g
```

If we had our code deployed to our server, we would then be able to start our app via PM2 but we will have to come back to this once our CI pipeline is complete.

Deploy with Github Actions

Now we can finally create a deployment pipeline in Github actions that automatically deploys our code to our new server (into the directory we created with the correct permissions). We will then move back to our ssh terminal in order to start our app.

Before we deploy anything, we are going to upload our previously downloaded ssh private key, into Github secrets so that we can reference it in our CI pipeline.

We are going to name ours SSH_PRIVATE_KEY:

Using the following yaml file, we do the following:

install dependencies
run build
run tests
use rsync to copy files to our server (it will replace existing files)

name: CI

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

  workflow_dispatch:

jobs:
  build:

    runs-on: ubuntu-latest

    if: github.ref == 'refs/heads/master'

    strategy:
      matrix:
        node-version: [14.x]

    steps:
      - uses: actions/checkout@v2

      - run: npm ci
      - run: npm run build
      - run: npm run test

      - name: rsync deployments
        uses: burnett01/rsync-deployments@5.1
        with:
          switches: -avzr --delete
          path: ./*
          remote_path: /var/www/my-app/
          remote_host: <host>.compute.amazonaws.com
          remote_user: ubuntu
          remote_key: "${{ secrets.SSH_PRIVATE_KEY }}"

Push this to our master branch in our Github repo and we should see an action run. If successful, our files should now be on our server in /var/www/my-app.

If we switch back to where we're ssh'd into our server, we can now start our app.

$ pm2 start /var/www/my-app/dist/index.js start --watch

In my case, when I run npm run build it outputs my built files into the dist directory. You may have a different path to where you start your app from.
Also, by adding --watch we allow pm2 to restart the service whenever the files change. I.e. after each deployment.
If you need to set any environment variables, you can do so like so (keep in mind you will need to restart your app afterwards).
```
$ export MY_ENV_VAR=foo_bar
```

We should now have successfuly setup NGINX, installed node (via NVM) and PM2 and setup a deployment pipeline in Github actions.

With any luck, our application should be available to the public via http://www.my-website.com or whatever domain name you configured.

Shout out in the comments if you have any questions or issues following this guide and I'll do my best to answer them.

Happy coding and look forward to any any feedback.

A grid layout with responsive squares

Andrew McCallum — Tue, 21 Sep 2021 17:13:16 +0000

With the advent of flex-box and grid it is now easier than every to create a nice, clean grid layout. But the question is, what should I use and how can I make it responsive?

Suppose I have the following HTML and want each square inside my grid to have equal proportions, even as the screen size changes.

<div class="square-container">

  <div class="square">
    <div class="content">
    </div>
  </div>

  <div class="square">
    <div class="content">
    </div>
  </div>

  <div class="square">
    <div class="content">
    </div>
  </div>

  <div class="square">
    <div class="content">
    </div>
  </div>

  <div class="square">
    <div class="content">
    </div>
  </div>

</div>

Lucky for us we can use either flex-box or grid to create a grid container and keep the width of each square equal. We can then use a little trick with padding-top: 100%; which will keep our square height the same as our width.

First up, our flex example:

.square-container {
  display: flex;
  flex-wrap: wrap;
}

.square {
  position: relative;
  flex-basis: calc(25% - 10px);
  margin: 5px;
  border: 1px solid;
  box-sizing: border-box;
}

.square::before {
  content: '';
  display: block;
  padding-top: 100%;
}

.square .content {
  position: absolute;
  top: 0; left: 0;
  height: 100%;
  width: 100%;
}

We end up with something like this:

By adding .square::before we are essentially adding an inner element to our square which has the same height as the parent squares width thanks to our little padding-top: 100%; trick. We can then position our square content over the top of this inner element and it will be a perfect square.

Similarly if you'd like to use grid to acheive the same thing, you can do something like this:

.square-container {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(30%, 1fr));
  grid-gap: 10px;
}

.square {
  position: relative;
  border: 1px solid;
  box-sizing: border-box;
}

.square::before {
  content: '';
  display: block;
  padding-top: 100%;
}

.square .content {
  position: absolute;
  top: 0; left: 0;
  height: 100%;
  width: 100%;
}

Hopefully by combining either flex-box or grid with the padding-top trick, you too can create grid layouts with responsive squares.