DEV Community: Marcos Schead

Understanding Closures in JavaScript: A Deep Dive

Marcos Schead — Wed, 24 Jul 2024 23:05:34 +0000

Closures are a fundamental concept in JavaScript, often considered a cornerstone of understanding how the language handles functions and scope. In this blog post, we'll explore the concept of closures step by step, using an example to illustrate how closures work in practice.

Step-by-Step Breakdown

Step 1: Define the Parent Function

First, we define a function named parent. Inside this function, a variable num is declared and initialized to 0.

function parent() {
  let num = 0;
}

This variable num is scoped to the parent function, meaning it cannot be accessed from outside the parent function.

Step 2: Define the Child Function

Next, within the parent function, we define another function named child.

function parent() {
  let num = 0;

  function child() {
    num += 1;
    console.log(num);
  }
}

The child function increments the num variable by 1 and logs its value to the console. The child function has access to the num variable because it is defined within the scope of the parent function.

Step 3: Return the Child Function

The parent function returns the child function. This is crucial because it means that when parent is called, it returns the child function, which retains access to the num variable even after parent has finished executing.

function parent() {
  let num = 0;

  function child() {
    num += 1;
    console.log(num);
  }

  return child;
}

Step 4: Create an Incrementer

Here, we call the parent function and store the returned child function in the incrementer variable.

const incrementer = parent();

At this point, incrementer is a function that can increment and log the num variable.

Step 5: Execute the Incrementer Function

We call the incrementer function twice. Each time it is called, the num variable is incremented by 1 and its value is logged to the console.

incrementer(); // Output: 1
incrementer(); // Output: 2

The output is 1 on the first call and 2 on the second call. This demonstrates that the num variable retains its state between function calls.

What is a Closure?

Closure in the Code Context

In the context of the code provided, a closure is created when the child function is defined within the parent function and returned. The child function retains access to the num variable defined in the parent function even after the parent function has finished executing. This retained access allows the child function to modify and log the num variable each time it is called.

Closure in General JavaScript Context

In a broader sense, a closure in JavaScript is when an inner function has access to variables in its outer enclosing function, even after the outer function has finished executing. This includes access to:

Its own scope (variables defined between its curly braces)
The scope of the outer function
The global scope

Closures enable powerful programming patterns such as data encapsulation, partial application, and function factories. They allow for the creation of private variables and functions, which can only be accessed and modified through the closure, promoting a cleaner and more modular code structure.

Conclusion

Closures are a powerful and essential feature of JavaScript, enabling functions to retain access to their lexical scope even when executed outside that scope. By understanding and utilizing closures, developers can create more modular, maintainable, and flexible code. The example provided demonstrates how closures work in practice, showing step-by-step how a function can retain access to variables defined in its parent scope.

Mastering closures is crucial for advanced JavaScript programming techniques, enabling you to write more robust and encapsulated code. Embracing closures can significantly enhance your ability to solve complex problems and create sophisticated applications.

Using Cypress Component Testing in your Next.js Application with TypeScript and GraphQL

Marcos Schead — Wed, 19 Jun 2024 21:00:03 +0000

Introduction

In my previous blog post, I discussed using React Testing Library to test React applications. Recently, Cypress introduced a new way to test components without requiring a full end-to-end solution. I decided to give it a try and was pleasantly surprised by its effectiveness. I seamlessly integrated it into my current project, which has a robust codebase. This type of testing is ideal for common scenarios, like the one I described in my last post, and I'll demonstrate it again here using Cypress. I've already covered the importance of testing in my previous blog, so let's dive straight into the code.

Step 1: Initialize the Repo

First, we'll create a new Next.js application. Currently, Cypress doesn't support Component Testing with server components or Next.js versions above 14. For more details, refer to the Next.js documentation on testing with Cypress.

I'm using Next.js to simplify the setup but feel free to user other solutions. The command below will generate a new application with Typescript.



npx create-next-app@latest blog-todo-graphql --typescript

Step 2: Install Apollo Client and GraphQL

Next, we'll install Apollo Client and GraphQL to handle our GraphQL queries and mutations. Also, don't forget the cypress library.



npm install @apollo/client graphql cypress

Step 3: Clean Up the Project Structure

We'll clean up the project structure by deleting the api folder.

Step 4: Adjust `index.tsx` File

Update the index.tsx file to include the following content:

pages/index.tsx



import AddTodo from "@/components/add-todo";
import ListTodos from "@/components/list-todos";

const Home = () => {
  return (
    <div>
      <h1>Todo List</h1>
      <AddTodo />
      <ListTodos />
    </div>
  );
};

export default Home;

Step 5: Add the Necessary Project Files

Here are the files we need to add to our project, along with a brief explanation of their purpose:

schemas/index.gql



type Todo {
  id: String!
  title: String!
  description: String!
}

type Query {
  todos: [Todo!]!
}

type Mutation {
  addTodo(title: String!, description: String!): Todo!
}

This file defines the GraphQL schema for our Todo application, including the Todo type, a query to fetch todos, and a mutation to add a new todo.

components/add-todo.tsx



import { useState } from "react";
import { useMutation, gql } from "@apollo/client";
import { GET_TODOS } from "@/components/list-todos";

export const ADD_TODO = gql`
  mutation AddTodo($title: String!, $description: String!) {
    addTodo(title: $title, description: $description) {
      id
      title
      description
    }
  }
`;

const AddTodo = () => {
  const [title, setTitle] = useState("");
  const [description, setDescription] = useState("");
  const [addTodo] = useMutation(ADD_TODO);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    await addTodo({
      variables: { title, description },
      refetchQueries: [{ query: GET_TODOS }],
    });
    setTitle("");
    setDescription("");
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="Title"
        required
      />
      <input
        value={description}
        onChange={(e) => setDescription(e.target.value)}
        placeholder="Description"
        required
      />
      <button type="submit">Add Todo</button>
    </form>
  );
};

export default AddTodo;

This component provides a form for adding new todos. It uses the Apollo Client to send a GraphQL mutation to add the todo and refetches the list of todos after adding a new one.

components/list-todos.tsx



import { useQuery, gql } from "@apollo/client";

export const GET_TODOS = gql`
  query GetTodos {
    todos {
      id
      title
      description
    }
  }
`;

const ListTodos = () => {
  const { loading, error, data } = useQuery(GET_TODOS);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return data.todos.map(
    (todo: { id: string; title: string; description: string }) => (
      <div key={todo.id}>
        <h3>{todo.title}</h3>
        <p>{todo.description}</p>
      </div>
    )
  );
};

export default ListTodos;

This component fetches and displays a list of todos using the Apollo Client. It shows loading and error states while the data is being fetched.

mocks/apollo-mock-provider.tsx



import React from "react";
import { MockedProvider, MockedResponse } from "@apollo/client/testing";

interface ApolloMockProviderProps {
  mocks: MockedResponse[];
  children: React.ReactNode;
}

const ApolloMockProvider: React.FC<ApolloMockProviderProps> = ({ mocks, children }) => (
  <MockedProvider mocks={mocks} addTypename={false}>
    {children}
  </MockedProvider>
);

export default ApolloMockProvider;

This component provides a mocked Apollo Client for testing purposes. It uses the MockedProvider from @apollo/client/testing to supply mock data for our tests.

tests/home.cy.tsx



import React from "react";
import Home from "../pages/index";
import { GET_TODOS } from "@/components/list-todos";
import { ADD_TODO } from "@/components/add-todo";
import ApolloMockProvider from "@/mocks/apollo-mock-provider";

const mocks = [
  {
    request: {
      query: ADD_TODO,
      variables: {
        title: "New Test Todo",
        description: "New Test Description",
      },
    },
    result: {
      data: {
        addTodo: {
          id: 1,
          title: "New Test Todo",
          description: "New Test Description",
        },
      },
    },
  },
  {
    request: {
      query: GET_TODOS,
    },
    result: {
      data: {
        todos: [
          {
            id: 1,
            title: "New Test Todo",
            description: "New Test Description",
          },
        ],
      },
    },
  },
];

describe("<Home />", () => {
  it("renders", () => {
    cy.mount(
      <ApolloMockProvider mocks={mocks}>
        <Home />
      </ApolloMockProvider>
    );

    cy.get('[placeholder="Title"]').type("New Test Todo");
    cy.get('[placeholder="Description"]').type("New Test Description");

    cy.get("button").click();

    cy.get("h3").should("contain", "New Test Todo");
    cy.get("p").should("contain", "New Test Description");
  });
});

This is our first Cypress test case. Similar to my approach with React Testing Library, this test verifies the functionality of adding a new todo to the list. It uses a mocked Apollo Provider to simulate GraphQL requests and responses.

In this example, I tested both <AddTodo /> and <ListTodos /> components through the Home page component. However, in some cases, it might be more practical to test components in isolation. For instance, if the Home page were a dashboard screen filled with various components, you would need to mock everything.

In such scenarios, testing each component individually is more effective, as the primary goal of these tests is to provide confidence during development. You'll quickly see that Cypress component testing mode makes this process straightforward and efficient.

Running Your Test

To open the Cypress Component Testing GUI, use the following command:



npx cypress open --component

You will need to configure a few settings, but the process is quick. Follow the instructions until you reach the screen shown below:

Pick your browser and select the home.cy.tsx test we created. It should display the following screen:

And there it is! Try creating tests for more complex cases that you encounter. For example, what if you have a complex form with two or more fields that depend on another field? These tests will provide quick feedback if you need to refactor this module at some point. Trust me, you might need to do it.

Benefits of Independent Tests

As you can see, in this setup, we didn't need to add the ApolloProvider component to our main application, just the MockedProvider for our tests. It's important to note that the ApolloProvider and MockedProvider serve different purposes and are independent of each other. Since this content focuses on demonstrating the tests and not the application running, we don't need to add the ApolloProvider here. However, in a real application, you must include the ApolloProvider to integrate your application with the actual API.

Conclusion

Frontend testing is an indispensable part of modern web development. It ensures that your application is reliable, maintainable, and provides a great user experience. If you read my previous article and tried using React Testing Library, you will find that Cypress Component Testing is much easier for more complex scenarios. Why not give this new approach a try and share your experiences with me? I’m eager to hear about your results. Happy testing!

Using React Testing Library to Test Your Next.js Application with TypeScript and GraphQL

Marcos Schead — Fri, 31 May 2024 17:20:10 +0000

Introduction

In the fast-paced web development world, ensuring your applications' quality and reliability is paramount. Testing is a critical component in the development process, especially for the frontend where user interaction is most prominent. Using modern tools like React, Next.js, TypeScript, GraphQL, and React Testing Library, developers can build robust and maintainable applications. In this blog post, we'll explore the importance of frontend testing and guide you through a practical example to get you started.

Why Frontend Testing Matters

Ensuring Code Quality

Frontend testing helps maintain high code quality by catching bugs early in the development process. It ensures that individual components function as expected, reducing the chances of errors in the production environment.

Enhancing User Experience

By testing user interactions and UI components, developers can ensure a seamless and bug-free user experience. This is crucial for retaining users and providing a smooth navigation experience.

Facilitating Refactoring

With a comprehensive suite of tests, developers can confidently refactor code without fear of breaking existing functionality. This encourages cleaner and more maintainable codebases.

Improving Collaboration

Testing promotes better collaboration among team members. Clear and concise tests serve as documentation for how components should behave, making it easier for new developers to understand the codebase.

Increasing Productivity

Automated tests save time in the long run by reducing the need for manual testing. This allows developers to focus on building new features and improving existing ones.

Practical Example: Setting Up Frontend Testing

Let's dive into a practical example to illustrate how to set up and run frontend tests in a Next.js application with TypeScript, GraphQL, and React Testing Library.

Step 1: Initialize the Repo

First, we'll create a new Next.js application using a predefined example with Jest for testing.

npx create-next-app@latest --example with-jest blog-todo-graphql --typescript

Step 2: Install Apollo Client and GraphQL

Next, we'll install the Apollo Client and GraphQL to handle our GraphQL queries and mutations.

npm install @apollo/client graphql

Step 3: Update `tsconfig.json`

To ensure that our imports are correctly resolved, update the tsconfig.json file to include the following paths configuration:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Step 4: Update React Testing Library

Ensure that you have the latest version of React Testing Library for the best features and bug fixes.

npm install @testing-library/react@15.0.6

Step 5: Clean Up the Project Structure

We'll clean up the project structure by deleting unnecessary files and folders. Keep only the app folder with page.tsx and layout.tsx files.

rm -rf pages __tests__

Step 6: Adjust `page.tsx` File

Update the page.tsx file to include the following content:

app/page.tsx

export const metadata = {
  title: "App Router",
};

import AddTodo from "@/components/add-todo";
import ListTodos from "@/components/list-todos";

const Home = () => {
  return (
    <div>
      <h1>Todo List</h1>
      <AddTodo />
      <ListTodos />
    </div>
  );
};

export default Home;

Step 7: Add the Necessary Project Files

Here are the files we need to add to our project, along with a brief explanation of their purpose:

schemas/index.gql

type Todo {
  id: String!
  title: String!
  description: String!
}

type Query {
  todos: [Todo!]!
}

type Mutation {
  addTodo(title: String!, description: String!): Todo!
}

This file defines the GraphQL schema for our Todo application, including the Todo type, a query to fetch todos, and a mutation to add a new todo.

components/add-todo.tsx

import { useState } from "react";
import { useMutation, gql } from "@apollo/client";
import { GET_TODOS } from "@/components/list-todos";

export const ADD_TODO = gql`
  mutation AddTodo($title: String!, $description: String!) {
    addTodo(title: $title, description: $description) {
      id
      title
      description
    }
  }
`;

const AddTodo = () => {
  const [title, setTitle] = useState("");
  const [description, setDescription] = useState("");
  const [addTodo] = useMutation(ADD_TODO);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    await addTodo({
      variables: { title, description },
      refetchQueries: [{ query: GET_TODOS }],
    });
    setTitle("");
    setDescription("");
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="Title"
        required
      />
      <input
        value={description}
        onChange={(e) => setDescription(e.target.value)}
        placeholder="Description"
        required
      />
      <button type="submit">Add Todo</button>
    </form>
  );
};

export default AddTodo;

This component provides a form for adding new todos. It uses the Apollo Client to send a GraphQL mutation to add the todo and refetches the list of todos after adding a new one.

components/list-todos.tsx

import { useQuery, gql } from "@apollo/client";

export const GET_TODOS = gql`
  query GetTodos {
    todos {
      id
      title
      description
    }
  }
`;

const ListTodos = () => {
  const { loading, error, data } = useQuery(GET_TODOS);

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {data.todos.map(
        (todo: { id: string; title: string; description: string }) => (
          <li key={todo.id}>
            <h3>{todo.title}</h3>
            <p>{todo.description}</p>
          </li>
        )
      )}
    </ul>
  );
};

export default ListTodos;

This component fetches and displays a list of todos using the Apollo Client. It shows loading and error states while the data is being fetched.

mocks/apollo-mock-provider.tsx

import React from "react";
import { MockedProvider, MockedResponse } from "@apollo/client/testing";

interface ApolloMockProviderProps {
  mocks: MockedResponse[];
  children: React.ReactNode;
}

const ApolloMockProvider: React.FC<ApolloMockProviderProps> = ({ mocks, children }) => (
  <MockedProvider mocks={mocks} addTypename={false}>
    {children}
  </MockedProvider>
);

export default ApolloMockProvider;

This component provides a mocked Apollo Client for testing purposes. It uses the MockedProvider from @apollo/client/testing to supply mock data for our tests.

tests/add-todo.test.tsx

import { render, screen, fireEvent } from "@testing-library/react";
import ApolloMockProvider from "@/mocks/apollo-mock-provider";
import { ADD_TODO } from "@/components/add-todo";
import { GET_TODOS } from "@/components/list-todos";
import Home from "app/page";

const mocks = [
  {
    request: {
      query: ADD_TODO,
      variables: {
        title: "New Test Todo",
        description: "New Test Description",
      },
    },
    result: {
      data: {
        addTodo: {
          id: 1,
          title: "New Test Todo",
          description: "New Test Description",
        },
      },
    },
  },
  {
    request: {
      query: GET_TODOS,
    },
    result: {
      data: {
        todos: [],
      },
    },
  },
  {
    request: {
      query: GET_TODOS,
    },
    result: {
      data: {
        todos: [
          {
            id: 1,
            title: "New Test Todo",
            description: "New Test Description",
          },
        ],
      },
    },
  },
];

test("adds a todo", async () => {
  render(
    <ApolloMockProvider mocks={mocks}>
      <Home />
    </ApolloMockProvider>
  );

  // Check that initially there are no todos
  expect(screen.queryByText("New Test Todo")).not.toBeInTheDocument();
  expect(screen.queryByText("New Test Description")).not.toBeInTheDocument();

  // Add a new todo
  fireEvent.change(screen.getByPlaceholderText(/title/i), {
    target: { value: "New Test Todo" },
  });
  fireEvent.change(screen.getByPlaceholderText(/description/i), {
    target: { value: "New Test Description" },
  });

  fireEvent.click(screen.getByText("Add Todo"));

  // Check that the new todo is added
  expect(await screen.findByText("New Test Todo")).toBeInTheDocument();
  expect(await screen.findByText("New Test Description")).toBeInTheDocument();
});

This test checks the functionality of adding a new todo. It uses the mocked Apollo Provider to simulate the GraphQL requests and responses.

tests/list-todos.test.tsx

import { render, screen } from "@testing-library/react";
import ListTodos from "@/components/list-todos";
import ApolloMockProvider from "@/mocks/apollo-mock-provider";
import { GET_TODOS } from "@/components/list-todos";

const mocks = [
  {
    request: {
      query: GET_TODOS,
    },
    result: {
      data: {
        todos: [
          { id: 1, title: "Test Todo 1", description: "Test Description 1" },
          { id: 2, title: "Test Todo 2", description: "Test Description 2" },
        ],
      },
    },
  },
];

test("lists all todos", async () => {
  render(
    <ApolloMockProvider mocks={mocks}>
      <ListTodos />
    </ApolloMockProvider>
  );

  expect(screen.getByText("Loading...")).toBeInTheDocument();

  expect(await screen.findByText("Test Todo 1")).toBeInTheDocument();
  expect(await screen.findByText("Test Description 1")).toBeInTheDocument();

  expect(await screen.findByText("Test Todo 2")).toBeInTheDocument();
  expect(await screen.findByText("Test Description 2")).toBeInTheDocument();
});

This test checks that the list of todos is correctly fetched and displayed. It uses the mocked Apollo Provider to supply the test data.

Benefits of Independent Tests

To run the tests, use the command below

npm run test

Conclusion

Frontend testing is an indispensable part of modern web development. It ensures that your application is reliable, maintainable, and provides a great user experience. By integrating testing into your workflow, you can build robust applications with confidence. Follow the steps and add the provided files to set up a solid testing environment for your Next.js application. Happy testing!

Building Robust Applications in React with TypeScript and Zod for REST API Validation

Marcos Schead — Thu, 23 May 2024 16:54:55 +0000

When building applications with React and TypeScript, leveraging TypeScript's static typing capabilities can significantly enhance your code's reliability. However, even with TypeScript, you can't guarantee the shape and type of data coming from external APIs. This potential discrepancy can lead to runtime errors that disrupt your application's functionality. In this blog post, we'll explore how to handle such situations using Zod, a TypeScript-first schema declaration and validation library.

Scenario: Fetching User Data with TypeScript

Imagine you have a React application that fetches user data from an API. The User object has a phoneNumber property, which is expected to be a string. You'll format this phone number to display it in a user-friendly manner. Here's how you might start:

// types.ts
export interface User {
  id: number;
  name: string;
  phoneNumber: string;
}

// api.ts
export const fetchUser = async (userId: number): Promise<User> => {
  const response = await fetch(`https://api.example.com/users/${userId}`);
  const data: User = await response.json();
  return data;
};

// UserComponent.tsx
import React, { useEffect, useState } from 'react';
import { User } from './types';
import { fetchUser } from './api';

const UserComponent: React.FC<{ userId: number }> = ({ userId }) => {
  const [user, setUser] = useState<User | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    fetchUser(userId)
      .then(setUser)
      .catch(err => setError(err.message));
  }, [userId]);

  if (error) return <div>Error: {error}</div>;
  if (!user) return <div>Loading...</div>;

  const formattedPhoneNumber = formatPhoneNumber(user.phoneNumber);

  return (
    <div>
      <h1>{user.name}</h1>
      <p>Phone: {formattedPhoneNumber}</p>
    </div>
  );
};

const formatPhoneNumber = (phoneNumber: string): string => {
  // Logic to format the phone number
  return phoneNumber.replace(/(\d{3})(\d{3})(\d{4})/, '($1) $2-$3');
};

export default UserComponent;

In this example, we expect phoneNumber to be a string. However, if the backend changes phoneNumber to a number, this will lead to a runtime error in the formatPhoneNumber function.

Runtime Error Example

Suppose the backend now sends:

{
  "id": 1,
  "name": "John Doe",
  "phoneNumber": 1234567890
}

This change will cause a runtime error in the formatPhoneNumber function because replace is not a method on numbers. The error will look like this:

TypeError: phoneNumber.replace is not a function

This error indicates that phoneNumber is not a string as expected, but a number, leading to the failure of the replace method.

Introducing Zod for Schema Validation

To safeguard against such issues, we can use Zod to validate the data we receive from the API. Here's how we can do it step-by-step:

Install Zod :

npm install zod

Define a Zod Schema :

// schema.ts
import { z } from 'zod';

export const userSchema = z.object({
  id: z.number(),
  name: z.string(),
  phoneNumber: z.string(),
});

export type User = z.infer<typeof userSchema>;

Validate API Response and Provide Feedback :

// api.ts
import { userSchema, User } from './schema';

export const fetchUser = async (userId: number): Promise<User> => {
  const response = await fetch(`https://api.example.com/users/${userId}`);
  const data = await response.json();

  const result = userSchema.safeParse(data);

  if (!result.success) {
    console.error("Validation Error:", result.error.format());
    throw new Error('Invalid data format');
  }

  return result.data;
};

Handle Validation in the Component :

// UserComponent.tsx
import React, { useEffect, useState } from 'react';
import { User } from './schema';
import { fetchUser } from './api';

const UserComponent: React.FC<{ userId: number }> = ({ userId }) => {
  const [user, setUser] = useState<User | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    fetchUser(userId)
      .then(setUser)
      .catch(err => setError(err.message));
  }, [userId]);

  if (error) return <div>Error: {error}</div>;
  if (!user) return <div>Loading...</div>;

  const formattedPhoneNumber = formatPhoneNumber(user.phoneNumber);

  return (
    <div>
      <h1>{user.name}</h1>
      <p>Phone: {formattedPhoneNumber}</p>
    </div>
  );
};

const formatPhoneNumber = (phoneNumber: string): string => {
  // Logic to format the phone number
  return phoneNumber.replace(/(\d{3})(\d{3})(\d{4})/, '($1) $2-$3');
};

export default UserComponent;

In this updated example, the fetchUser function uses the Zod schema to validate the API response. If the data doesn't match the expected schema, an error is thrown, and a detailed validation error is logged to the console. This feedback helps developers quickly identify and resolve issues with the API data.

Error Message Example

With the Zod validation in place, if the backend sends the phoneNumber as a number, the application will catch this discrepancy and throw an error. The console will log a detailed error message like this:

Validation Error: {
  "phoneNumber": {
    "_errors": ["Expected string, received number"]
  }
}

In addition to logging the error, the application will throw an error to the user with the message:

Error: Invalid data format

This message indicates to the user that there was an issue with the data received from the API.

Conclusion

Using Zod for schema validation in your React and TypeScript applications ensures that your application can gracefully handle unexpected changes in the API response structure. This approach helps you catch potential issues early, leading to more robust and reliable applications. By incorporating Zod into your development workflow, you can enhance your application's resilience against API changes and reduce runtime errors.

Remember, while TypeScript provides excellent compile-time type checking, runtime validation with tools like Zod is essential for dealing with external data sources. This combination ensures that your application remains stable and predictable, even when the data it relies on changes unexpectedly.

Ensuring Environment Variable Integrity with Zod in TypeScript

Marcos Schead — Thu, 16 May 2024 17:02:25 +0000

Managing environment variables effectively is crucial in any application, whether it’s a frontend or backend. Missing or misconfigured environment variables can lead to hard-to-debug runtime errors. Fortunately, the Zod library offers a simple yet powerful solution for schema validation, which can be leveraged to validate environment variables upfront. In this blog post, we'll explore how to use Zod to ensure all necessary environment variables are set correctly, preventing unexpected runtime issues.

Additionally, we will cover how to manage environment variables using a .env file in a Node.js project with TypeScript.

What is Zod?

Zod is a TypeScript-first schema declaration and validation library. It provides a straightforward way to define schemas and validate data against these schemas. It can be used to validate inputs, responses, and, importantly, environment variables.

Why Validate Environment Variables?

Environment variables are used to configure various aspects of an application, such as database connections, API endpoints, and ports. If these variables are missing or misconfigured, your application might crash or behave unpredictably. Validating these variables at startup ensures that all required configuration is present and correctly formatted, providing an early failure mechanism that saves time and effort in debugging.

Step-by-Step Guide to Using Zod for Environment Variables

Let’s walk through how to set up Zod to validate environment variables in a TypeScript project and how to use a .env file to manage these variables.

Step 1: Initialize Your Node.js Project

First, you need to initialize a new Node.js project if you haven't already. This will create a package.json file to manage your project's dependencies and scripts.

npm init -y

Step 2: Install Dependencies

Next, install Zod and dotenv in your project. You will also need express, @types/express, @types/node, and ts-node for a complete setup.

npm install zod dotenv express
npm install --save-dev @types/express @types/node ts-node typescript

Step 3: Set Up TypeScript Configuration

Ensure your tsconfig.json is properly configured for TypeScript. Here is a basic example:

{
  "compilerOptions": {
    "target": "ES6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"],
  "exclude": ["node_modules"]
}

Step 4: Create a `.env` File

Create a .env file in the root of your project. This file will store your environment variables.

PORT=3000
BASE_URL=http://localhost

Step 5: Configure `dotenv` in Your Project

Create a new file, env.ts, where you will configure dotenv and define the schema for your environment variables using Zod.

import { z } from 'zod';
import dotenv from 'dotenv';

dotenv.config();

const envSchema = z.object({
  PORT: z
    .string()
    .refine(
      (port) => parseInt(port) > 0 && parseInt(port) < 65536,
      "Invalid port number"
    ),
  BASE_URL: z
    .string()
    .refine(
      (url) => url.startsWith("http") || url.startsWith("https"),
      "Invalid URL format"
    ),
});

type Env = z.infer<typeof envSchema>;

export const ENV: Env = envSchema.parse(process.env);

In this schema, we define that PORT and BASE_URL are required environment variables and should be strings. The PORT must be a valid port number between 1 and 65535, and BASE_URL must start with "http" or "https". The z.infer utility type is used to infer the TypeScript type from the schema.

Step 6: Validate the Environment Variables

By calling envSchema.parse(process.env), Zod will validate the process.env object against the defined schema. If any of the variables are missing or do not match the defined type, Zod will throw an error, causing your application to crash with a clear message about what’s wrong.

Step 7: Integrate the Validation in Your Application

To ensure the validation runs before the rest of your application, import the env.ts file at the very start of your main entry file, usually index.ts.

import { ENV } from './env';

// Rest of your application code
import express from 'express';

const app = express();
const port = Number(ENV.PORT);

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(port, () => {
  console.log(`Server running at ${ENV.BASE_URL}:${port}`);
});

Step 8: Running Your TypeScript Project

Make sure to run your project using ts-node. You can add a script to your package.json to make this easier:

{
  "scripts": {
    "start": "ts-node src/index.ts"
  }
}

Step 9: Demonstrate the Validation

To see Zod's validation in action, intentionally set an incorrect value in the .env file. For example, set PORT to an invalid number and BASE_URL to a string that doesn't start with "http" or "https".

Modify your .env file as follows:

PORT=70000
BASE_URL=localhost

Run your application using the start script:

npm start

You should see an error message indicating the invalid values:

Invalid environment variables: [
  {
    "path": ["PORT"],
    "message": "Invalid port number"
  },
  {
    "path": ["BASE_URL"],
    "message": "Invalid URL format"
  }
]

Conclusion

Using Zod to validate your environment variables is a straightforward and effective way to prevent configuration-related issues. By defining a schema and validating your environment variables at startup, you can ensure that your application fails early and clearly, saving time and avoiding potential runtime errors. This approach can be applied to both frontend and backend environments, making it a versatile tool in your development toolkit.

Additionally, leveraging the dotenv package allows you to manage your environment variables in a simple and organized manner, especially useful in a Node.js project with TypeScript.

Give it a try in your next TypeScript project and experience the peace of mind that comes with knowing your environment is correctly configured from the get-go. Happy coding!

Using Clean Architecture and the Unit of Work Pattern on a Node.js Application

Marcos Schead — Thu, 09 May 2024 18:14:55 +0000

Introduction

In the realm of software development, the pursuit of clean architecture is akin to the quest for the Holy Grail. It's the cornerstone of building applications that are not only robust and scalable but also maintainable over time. Central to the concept of clean architecture are design patterns that help structure code in a way that promotes separation of concerns and modularization.

Two such indispensable patterns are the Repository and the Unit of Work. These patterns play a vital role in abstracting data access logic and managing transactions within an application, respectively. By employing these patterns effectively, developers can ensure their code remains organized, flexible, and easy to maintain.

In this tutorial, we'll embark on a journey through the implementation of the Repository and Unit of Work patterns using TypeScript and Node.js. However, instead of interfacing with databases, we'll opt for memory implementations to show that you can test your application layer without relying on external dependencies. Through practical examples and code snippets, we'll unravel the intricacies of these patterns and explore how they contribute to the foundation of clean architecture in modern software development.

So, fasten your seatbelts as we dive into the world of clean architecture and discover the power of the Repository and Unit of Work patterns in crafting elegant and maintainable code.

Setting Up the Project

Before we delve into the implementation of the Repository and Unit of Work patterns, let's ensure our development environment is set up and ready to go. In this section, we'll cover the basic setup of a TypeScript project in a Node.js environment, including the project structure and installation of necessary dependencies.

Project Structure

To maintain a clean and organized codebase, let's structure our project as follows:

project-root/
│
├── src/
│   ├── Account.ts
│   ├── Transaction.ts
│   ├── IRepository.ts
│   ├── IUnitOfWork.ts
│   ├── InMemoryRepository.ts
│   ├── InMemoryUnitOfWork.ts
│   └── TransferMoneyUseCase.ts
│   └── TransferMoneyUseCase.test.ts
│
├── package.json
└── tsconfig.json
└── jest.config.js

src/: This directory will contain all our TypeScript source files.
- Account.ts: Definition of the Account domain model.
- Transaction.ts: Definition of the Transaction domain model.
- IRepository.ts: Interface for the Repository pattern.
- IUnitOfWork.ts: Interface for the Unit of Work pattern.
- InMemoryRepository.ts: Implementation of the Repository pattern using memory.
- InMemoryUnitOfWork.ts: Implementation of the Unit of Work pattern using memory.
- TransferMoneyUseCase.ts: Use case to achieve our domain objective.
- TransferMoneyUseCase.test.ts: An integration test to ensure the use case works from an application perspective.
package.json: Configuration file for npm dependencies and scripts.
tsconfig.json: Configuration file for TypeScript compiler options.
jest.config.js: Configuration file for Jest.

Installing Dependencies

To get started, ensure you have Node.js and npm (or yarn) installed on your system. Then, initialize a new Node.js project by running the following command in your project directory:

npm init -y

Next, install TypeScript as a development dependency:

npm install typescript --save-dev

Additionally, we'll need @types/node to provide type definitions for Node.js:

npm install @types/node --save-dev

With TypeScript installed, we're ready to configure our project to use it. Create a tsconfig.json file in the root of your project and add the following configuration:

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*.ts"]
}

This configuration tells TypeScript to compile our code to ES6, use CommonJS modules, and output the compiled JavaScript files to the dist directory. It also enables strict type-checking and ES module interop.

Finally, you will need to install jest to run our use case scenario:

 npm i @types/jest jest ts-jest

Create a jest.config.js file in the root of your project and add the following configuration:

/** @type {import('ts-jest').JestConfigWithTsJest} */
module.exports = {
  preset: "ts-jest",
  testEnvironment: "node",
  moduleNameMapper: {
    "src/(.*)": "<rootDir>/src/$1",
  },
};

With our project structure set up and dependencies installed, we're now ready to start implementing the Repository and Unit of Work patterns in TypeScript!

Defining Domain Models

Before we dive into the implementation of the Repository and Unit of Work patterns, let's define the domain models that will form the foundation of our application. In this section, we'll create simple yet essential models for representing accounts and transactions.

Account Model

The Account model represents a user's account in our system. It encapsulates basic information such as the account ID and the current balance.

export class Account {
  constructor(public id: string, public balance: number) {}
}

The Account class consists of two properties:

id: A unique identifier for the account.
balance: The current balance of the account.

Transaction Model

The Transaction model represents a financial transaction between two accounts. It contains information about the transaction ID, the IDs of the sender and receiver accounts, and the transaction amount.

export class Transaction {
  constructor(public id: string, public fromAccountId: string, public toAccountId: string, public amount: number) {}
}

The Transaction class includes the following properties:

id: A unique identifier for the transaction.
fromAccountId: The ID of the account from which the money is being sent.
toAccountId: The ID of the account to which the money is being sent.
amount: The amount of money involved in the transaction.

With our domain models defined, we have a solid foundation upon which to build the rest of our application. In the next sections, we'll explore how to implement the Repository and Unit of Work patterns to interact with these models in a clean and modular way.

Implementing the Repository Pattern

The Repository pattern is a fundamental part of clean architecture, serving as an abstraction layer between the application's business logic and the underlying data storage mechanism. In this section, we'll delve into how to implement the Repository pattern using TypeScript and Node.js, with memory implementations.

IRepository Interface

The IRepository interface defines the contract that all repository implementations must adhere to. It provides methods for basic CRUD (Create, Read, Update, Delete) operations on domain entities.

export interface IRepository<T> {
  findById(id: string): Promise<T | undefined>;
  findAll(): Promise<T[]>;
  save(entity: T): Promise<void>;
}

The IRepository interface consists of the following methods:

findById(id: string): Retrieves an entity by its unique identifier.
findAll(): Retrieves all entities stored in the repository.
save(entity: T): Saves or updates an entity in the repository.
InMemoryRepository Implementation

The InMemoryRepository class provides an implementation of the IRepository interface using an in-memory data store. This fake implementation will be used for testing purposes on the application layer. For the sake of simplicity, we'll use a JavaScript Map to store entities.

import { IRepository } from "./IRepository";

export class InMemoryRepository<T> implements IRepository<T> {
  private data: Map<string, T> = new Map();

  async findById(id: string): Promise<T | undefined> {
    return this.data.get(id);
  }

  async findAll(): Promise<T[]> {
    return Array.from(this.data.values());
  }

  async save(entity: T): Promise<void> {
    // For simplicity, assuming the entity has an 'id' property
    this.data.set((entity as any).id, entity);
  }
}

The InMemoryRepository class implements the methods defined in the IRepository interface by manipulating data stored in a Map. It provides basic functionality for finding, retrieving, and saving entities in memory.

By implementing the Repository pattern in this manner, we achieve a clean separation of concerns between the application's business logic and the data access layer. In the next section, we'll explore how to implement the Unit of Work pattern to manage transactions across multiple repositories effectively.

Implementing the Unit of Work Pattern

The Unit of Work pattern is a crucial aspect of clean architecture, responsible for coordinating multiple repository operations within a single transaction context. In this section, we'll delve into how to implement the Unit of Work pattern using TypeScript and Node.js, with memory implementations.

IUnitOfWork Interface

The IUnitOfWork interface defines the contract that all Unit of Work implementations must adhere to. It provides methods for accessing repository instances and managing transactional operations.

import { Account } from "./Account";
import { IRepository } from "./IRepository";
import { Transaction } from "./Transaction";

export interface IUnitOfWork {
  begin(): Promise<void>;
  commit(): Promise<void>;
  rollback(): Promise<void>;
  getAccountRepository(): IRepository<Account>;
  getTransactionRepository(): IRepository<Transaction>;
}

The IUnitOfWork interface consists of the following methods:

commit(): Commits all pending changes made within the unit of work.
rollback(): Rolls back all pending changes made within the unit of work.
getAccountRepository(): Retrieves the repository instance for managing accounts.
getTransactionRepository(): Retrieves the repository instance for managing transactions.

The InMemoryUnitOfWork class provides an implementation of the IUnitOfWork interface using memory repositories. It serves as a central coordinator for managing transactions across multiple repositories.

import { IUnitOfWork } from "./IUnitOfWork";
import { IRepository } from "./IRepository";
import { Account } from "./Account";
import { Transaction } from "./Transaction";
import { InMemoryRepository } from "./InMemoryRepository";

export class InMemoryUnitOfWork implements IUnitOfWork {
  private accounts: IRepository<Account>;
  private transactions: IRepository<Transaction>;

  constructor() {
    this.accounts = new InMemoryRepository<Account>();
    this.transactions = new InMemoryRepository<Transaction>();
  }

  async begin(): Promise<void> {
    // In a memory implementation, begin doesn't do anything
  }

  async commit(): Promise<void> {
    // In a memory implementation, commit doesn't do anything
  }

  async rollback(): Promise<void> {
    // In a memory implementation, rollback doesn't do anything
  }

  getAccountRepository(): IRepository<Account> {
    return this.accounts;
  }

  getTransactionRepository(): IRepository<Transaction> {
    return this.transactions;
  }
}

The InMemoryUnitOfWork class implements the methods defined in the IUnitOfWork interface by providing access to repository instances for accounts and transactions. It does not perform actual transaction management in memory implementations but serves as a placeholder for coordinating repository operations within a transaction context.

A real database implementation needs these operations to coordinate the atomicity between two or more repository writes. However, when testing specifically the use case, the focus is on the domain and not the technology.

By implementing the Unit of Work pattern in this manner, we enable efficient management of transactions and ensure data consistency across multiple repository operations. In the next section, we'll put the Repository and Unit of Work patterns into action by demonstrating a simple money transfer operation.

Putting It All Together

Now that we've implemented the Repository and Unit of Work patterns, it's time to demonstrate how they work together to perform a practical operation within our application. In this section, we'll illustrate a simple money transfer scenario, leveraging the capabilities provided by the Repository and Unit of Work implementations.

Money Transfer Function

We'll begin by implementing a function called TransferMoneyUseCase, which orchestrates the transfer of funds between two accounts. This function will utilize repository instances obtained from the Unit of Work to retrieve and update account balances, ensuring data consistency and integrity.

import { Transaction } from "./Transaction";
import { IUnitOfWork } from "./IUnitOfWork";

export async function TransferMoneyUseCase(
  unitOfWork: IUnitOfWork,
  fromAccountId: string,
  toAccountId: string,
  amount: number
) {
  try {
    await unitOfWork.begin();
    const accountRepository = unitOfWork.getAccountRepository();
    const fromAccount = await accountRepository.findById(fromAccountId);
    const toAccount = await accountRepository.findById(toAccountId);

    if (!fromAccount || !toAccount) {
      throw new Error("Account not found");
    }

    if (fromAccount.balance < amount) {
      throw new Error("Insufficient balance");
    }

    fromAccount.balance -= amount;
    toAccount.balance += amount;

    await accountRepository.save(fromAccount);
    await accountRepository.save(toAccount);

    const transactionRepository = unitOfWork.getTransactionRepository();
    const transactionId = Date.now().toString(); // Generate a simple unique transaction ID
    const transaction = new Transaction(
      transactionId,
      fromAccountId,
      toAccountId,
      amount
    );
    await transactionRepository.save(transaction);
    await unitOfWork.commit();
  } catch (err) {
    await unitOfWork.rollback();
    throw err;
  }
}

The TransferMoneyUseCase function coordinates the transfer of funds from one account to another. It first retrieves the sender and receiver account from the account repository, checks for sufficient balance in the sender's account, update the account balances accordingly and saves the changes to the repository. Additionally, it creates a new transaction record and saves it to the transaction repository.

The Use Case Test

With the TransferMoneyUseCase function in place, we can now demonstrate the money transfer operation through a test scenario. We'll create some initial accounts, perform a money transfer, and display the updated balances of the accounts.

import { Account } from "./Account";
import { InMemoryUnitOfWork } from "./InMemoryUnitOfWork";
import { TransferMoneyUseCase } from "./TransferMoneyUseCase";

test("Make a transfer between two accounts", async () => {
  const unitOfWork = new InMemoryUnitOfWork();

  // Create some initial accounts
  await unitOfWork.getAccountRepository().save(new Account("1", 1000));
  await unitOfWork.getAccountRepository().save(new Account("2", 500));

  // Transfer money from account 1 to account 2
  await TransferMoneyUseCase(unitOfWork, "1", "2", 200);

  // Check the updated account balances
  const updatedAccounts = await unitOfWork.getAccountRepository().findAll();
  const [first, second] = updatedAccounts;
  expect(first.balance).toBe(800);
  expect(second.balance).toBe(700);
});

Use the following command to run the test:

npx jest

In the test case function, we initialize a new instance of InMemoryUnitOfWork to manage our repository operations within a transaction context. We then create two initial accounts with different balances, perform a money transfer operation from one account to another, and then, verify if the final balances align with the expected results.

It was pretty straightforward and fast to run this test since there was no need to run a database. And that's the goal of this layer, make sure the application rules are correct. To be more specific, check if the accounts have the correct balances after the operation.

By the way, do you see we have an issue on the domain? What if the first account doesn't have enough balance to transfer? Try to add a new test scenario and change the code to make it work.

With the Repository and Unit of Work patterns put into action, we've successfully demonstrated how to build a clean and testable application architecture in TypeScript and Node.js, enabling efficient management of domain entities and transactions.

Conclusion

In this tutorial, we've embarked on a journey through the implementation of the Repository and Unit of Work patterns in TypeScript and Node.js, using memory implementations to show that you can test your application layer without relying on external dependencies, such as an SQL database. These patterns are indispensable tools in the arsenal of clean architecture, enabling developers to build robust, maintainable, and scalable applications.

Through practical examples and code snippets, we've explored how the Repository pattern abstracts data access logic, providing a clean separation between the application's business logic and the underlying data storage mechanism. By implementing repositories for our domain entities such as accounts and transactions, we've ensured that our code remains modular and easy to maintain.

Additionally, we've delved into the Unit of Work pattern, which serves as a central coordinator for managing transactions across multiple repositories. By encapsulating repository operations within a transaction context, we've achieved data consistency and integrity, even in the face of failures or exceptions during the operation.

As you continue your journey in software development, I encourage you to embrace these patterns and incorporate them into your projects. By adhering to clean architecture principles and leveraging the power of patterns like the Repository and Unit of Work, you can elevate the quality of your code and build applications that stand the test of time.

DEV Community: Marcos Schead

Understanding Closures in JavaScript: A Deep Dive

Step-by-Step Breakdown

Step 1: Define the Parent Function

Step 2: Define the Child Function

Step 3: Return the Child Function

Step 4: Create an Incrementer

Step 5: Execute the Incrementer Function

What is a Closure?

Closure in the Code Context

Closure in General JavaScript Context

Conclusion

Using Cypress Component Testing in your Next.js Application with TypeScript and GraphQL

Introduction

Step 1: Initialize the Repo

Step 2: Install Apollo Client and GraphQL

Step 3: Clean Up the Project Structure

Step 4: Adjust index.tsx File

Step 5: Add the Necessary Project Files

Running Your Test

Benefits of Independent Tests

Conclusion

Using React Testing Library to Test Your Next.js Application with TypeScript and GraphQL

Introduction

Why Frontend Testing Matters

Ensuring Code Quality

Enhancing User Experience

Facilitating Refactoring

Improving Collaboration

Increasing Productivity

Practical Example: Setting Up Frontend Testing

Step 1: Initialize the Repo

Step 2: Install Apollo Client and GraphQL

Step 3: Update tsconfig.json

Step 4: Update React Testing Library

Step 5: Clean Up the Project Structure

Step 6: Adjust page.tsx File

Step 7: Add the Necessary Project Files

Benefits of Independent Tests

Conclusion

Building Robust Applications in React with TypeScript and Zod for REST API Validation

Scenario: Fetching User Data with TypeScript

Runtime Error Example

Introducing Zod for Schema Validation

Error Message Example

Conclusion

Ensuring Environment Variable Integrity with Zod in TypeScript

What is Zod?

Why Validate Environment Variables?

Step-by-Step Guide to Using Zod for Environment Variables

Step 1: Initialize Your Node.js Project

Step 2: Install Dependencies

Step 3: Set Up TypeScript Configuration

Step 4: Create a .env File

Step 5: Configure dotenv in Your Project

Step 6: Validate the Environment Variables

Step 7: Integrate the Validation in Your Application

Step 8: Running Your TypeScript Project

Step 9: Demonstrate the Validation

Conclusion

Using Clean Architecture and the Unit of Work Pattern on a Node.js Application

Introduction

Setting Up the Project

Project Structure

Installing Dependencies

Defining Domain Models

Account Model

Transaction Model

Implementing the Repository Pattern

IRepository Interface

Implementing the Unit of Work Pattern

IUnitOfWork Interface

Putting It All Together

Money Transfer Function

The Use Case Test

Conclusion

Step 4: Adjust `index.tsx` File

Step 3: Update `tsconfig.json`

Step 6: Adjust `page.tsx` File

Step 4: Create a `.env` File

Step 5: Configure `dotenv` in Your Project