DEV Community: Michael Musatov

A Toy Django REST API with an Admin Panel

Michael Musatov — Fri, 07 Nov 2025 10:32:59 +0000

As a developer working primarily with Next.js and NestJS, I recently reviewed a pull request to a Django project authored by another developer — and realized just how much the Python ecosystem has evolved since I last used it professionally. In this post, I’ll document the process of setting up a modern Python + Django environment from a Node.js developer’s perspective.

The Python Environment setup

Since I last used Python professionally, the ecosystem has changed. virtualenv is still around and doing fine, but venv has been part of the standard library since Python 3.3. And now there’s uv — a modern, fast tool trying to consolidates the functionality of multiple utilities.

Let's compare them across virtual environments, project management, and packaging. Spoiler: I'm currently preferring uv for new projects.

With virtualenv, installation is done via pip install virtualenv command (pipx is optional), and the setup usually looks like virtualenv venv && source venv/bin/activate. New packages are installed with pip install <package>, and dependencies are frozen with pip freeze > requirements.txt installation of frozen dependencies is pip install -r requirements.txt. And a modern approach is to use pyproject.toml for projects management and dependencies management. Installing defined dependencies with pip install . or pip install -e . in development. Requires pip-tools or Pipenv for locking dependencies.
With venv, everything works almost the same, except there's no need to install an extra tool — just run python -m venv venv && source venv/bin/activate.
The uv tool takes it a bit differently. It's installed with curl -LsSf https://astral.sh/uv/install.sh | sh (or pipx install uv) and initialized using uv venv && source .venv/bin/activate. Packages are managed with uv add <package>, which automatically generates a pyproject.toml (if missing) and a uv.lock file for dependency locking. Dependencies for the entire project can be installed with uv sync.

In practice, uv replaces virtualenv/venv (environment creation), pip (package installation), pip-tools(dependency resolution), and pipx (tool installation via uv tool install), while partially covering poetry, pdm, and pyenv. The result is an opinionated but efficient workflow — fast, consistent, and simple.

If you’re coming from the Node.js world, the setup will feel somewhat familiar at first — though there are some fundamental differences. nvm manages different versions of the Node.js interpreter installed centrally under ~/.nvm, along with any global dependencies tied to those versions. In contrast, venv, virtualenv, and uv (which builds on venv) manage project-specific dependencies by creating an isolated Python environment. Each environment includes its own package directory and a dedicated copy (or symlinks) of the Python interpreter and its supporting files. When you activate it, your shell’s PATH is updated to use this local interpreter and its packages — effectively sandboxing everything to that single project.

Django Setup

With the environment ready, it's time to get to the point - setup Django. The official Django tutorial walks through the process in great detail, but here's the quick version.

First, install Django into your active environment with uv add django (or pip install django if you’re going old school). Then create a new project using django-admin startproject demo ., which generates the initial project structure and configuration.

Run the development server with python manage.py runserver and open the suggested URL in your browser — if everything works, you'll see Django's default "The install worked successfully! Congratulations!" page.

When you're building your Django app locally, you use the built-in development server python manage.py runserver. This is perfect for coding - it automatically reloads when you change files and shows detailed error pages if you mess up. But this server is slow and insecure. Dev server is WSGI, which you'll recognize from the wsgi.py file in your Django project.

When you're ready to show your app to the world, you need a production server that can handle real traffic. This is where ASGI servers like Daphne or Uvicorn come in - they're built for speed and security. You combine these with a proper web server like gunicorn, and suddenly your app can actually survive in the wild instead of just running on your laptop.

A toy API service

Let’s start by preparing the database and admin panel. We already have some pending migrations from the initial project scaffolding, so let’s apply them first. There’s no need to change any database settings — SQLite is a perfectly fine choice for a toy project. Run the migrations to create the database structures Django needs for the admin application with python manage.py migrate, and then create a superuser using python manage.py createsuperuser --username admin --email your@email.com.

Now we can set up the API service. We’ll use Django REST Framework (DRF) — because we’re lazy and smart enough not to reinvent the wheel. Add the package with uv add djangorestframework; it will immediately appear in your pyproject.toml. Then create a new API app with cd demo && django-admin startapp api.

Next, we’re ready to define some models. For the sake of the demo, let’s implement a toy CRUD structure: Category -> Product -> Review:

class Category(models.Model):
    name = models.CharField(max_length=100)

    def __str__(self):
        return self.name

class Product(models.Model):
    category = models.ForeignKey(Category, on_delete=models.CASCADE)
    name = models.CharField(max_length=100)
    description = models.TextField()
    price = models.DecimalField(max_digits=10, decimal_places=2)

    def __str__(self):
        return f"{self.name} ({self.category}) - ${self.price}"


class Review(models.Model):
    product = models.ForeignKey(Product, on_delete=models.CASCADE)
    rating = models.IntegerField()
    comment = models.TextField()

    def __str__(self):
        return f"Review for {self.product.name}: {self.rating} stars"

Note this little override of the __str__ method — it’s going to be quite useful. In Django, this defines how an object is represented as text. By returning self.name, records of this model will display that name in the admin interface and anywhere else the object appears as a string.

With the models in place, we define serializers api/serializers.py and views api/views.py. DRF serializers describe how models are converted to and from JSON:

class CategorySerializer(serializers.ModelSerializer):
    class Meta:
        model = Category
        fields = ["name"]

class ProductSerializer(serializers.ModelSerializer):
    class Meta:
        model = Product
        fields = ["category", "name", "description", "price"]

class ReviewSerializer(serializers.ModelSerializer):
    class Meta:
        model = Review
        fields = ["product", "rating", "comment"]

By default, all model fields are automatically mapped to corresponding serializer fields. However, it’s usually better to be explicit and define them yourself — at least to avoid unintentional exposure of internal fields you didn’t mean to show to the world.

With views we are going with public CRUD for simplicity reasons:

class CategoriesViewSet(viewsets.ModelViewSet):
    queryset = Category.objects.all()
    serializer_class = CategorySerializer
    permission_classes = [permissions.AllowAny]

class ProductsViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    permission_classes = [permissions.AllowAny]

class ReviewsViewSet(viewsets.ModelViewSet):
    queryset = Review.objects.all()
    serializer_class = ReviewSerializer
    permission_classes = [permissions.AllowAny]

With that set, we just need to configure routing inside our API app api/urls.py:

from django.urls import path, include
from rest_framework import routers
from . import views

router = routers.DefaultRouter(trailing_slash=False)
router.register(r"categories", views.CategoriesViewSet)
router.register(r"products", views.ProductsViewSet)
router.register(r"reviews", views.ReviewsViewSet)

urlpatterns = [
    path("", include(router.urls)),
]

Don’t forget to add the demo.api app and rest_framework to the project’s INSTALLED_APPS (missing either of these will break things) settings.py:

INSTALLED_APPS = [
    ...
    "rest_framework",
    "demo.api",
]

One more important step is to register our models with the admin so we can manage them through the UI api/admin.py:

from django.contrib import admin
from demo.api.models import Category, Product, Review

admin.site.register(Category)
admin.site.register(Product)
admin.site.register(Review)

With all that in place, create migrations for the new models using python manage.py makemigrations api and apply them with python manage.py migrate.

At this point everything is wired up and we can start the application with python manage.py runserver. A quick curl http://localhost:8000/api/reviews should return an empty array, which is exactly what we expect for a fresh database. Now you can go to /admin/, log in with the superuser you created earlier, add a category, a product, and a review — and then hit the same API endpoint again to see the data flowing through the API.

If you’re a Node.js developer, Django’s automatic admin interface might feel almost magical — there’s really no direct equivalent. In the JavaScript world, you usually mix and match tools to get something similar.

For the data access layer, frameworks like Prisma or TypeORM can generate models, migrations, and typed queries from schema definitions — that’s about as close as it gets to Django’s ORM. For an admin panel, you’d typically reach for AdminJS, which can auto-generate CRUD UIs on top of your models. Another option is Strapi, which works more like a highly customizable headless CMS with a built-in admin interface.

While none of these provide the same tight, batteries-included integration Django offers out of the box, a setup using Prisma + AdminJS (or Strapi if you prefer a full CMS) can get you a comparable developer experience — but with a few more moving parts to glue together.

Conclusion

I had some fun setting up this little toy project and dusting off my long-forgotten Python knowledge. Turns out, Django can be a pretty nice tool for managing data in a database while also providing an extensible API layer.

Next, I want to explore adding filtering, sorting, and pagination for all entities through the API — to see if this setup could really serve as a replacement for a headless CMS.

Also, since I recently had to deal with monitoring Django services running in GCP, I’m planning to set up OpenTelemetry. Let’s see how long it takes me to turn those experiments into the next blog post (or a few of them). 😅

By the way, I’ve pushed this little toy project to GitHub — feel free to explore. And there is mirror of this article on my personal website.

The Subtle Trap of ISO Date Strings in JavaScript

Michael Musatov — Mon, 26 May 2025 16:47:26 +0000

If you’re building any kind of real application, sooner or later you’ll be wrangling dates and times. And the moment your users live in different time zones, things get… interesting. I’ve hit this wall dozens of times — each encounter requiring a quick mental reset, a bit of digging, and a careful rethink of how to handle it all correctly.

There’s a fantastic (and slightly terrifying) post on the topic — Falsehoods Programmers Believe About Time — that’s absolutely worth a read. But today, I want to zero in on one specific gotcha: how JavaScript parses ISO date strings, and why new Date(str) and parseISO(str) from date-fns might not behave the way you expect.

Where It All Begins

In the project I was reviewing, dates were stored in ISO 8601 format—but in three different ways:

Full datetime with a trailing Z (explicit UTC)
Full datetime without the Z (no time zone info)
Date-only strings with no time component

On the client side, both new Date(str) and parseISO(str) were used throughout the codebase to parse these values. The result? A mix of behaviors and some surprisingly inconsistent experiences for end users.

Let’s break down each case and figure out a more predictable, less confusing approach.

1. Full ISO datetime with ending `Z`

This one’s straightforward. Both parseISO(str) and new Date(str) do the same thing here: they parse the timestamp as UTC and convert it to the browser’s local time zone. More over it is a part of ISO8601 standard: The ‘Z’ is shorthand for zero-hour offset (+00:00), meaning the time given is aligned exactly with UTC time.

const iso = '2011-07-21T15:00:00Z';

In an EST browser, this becomes:

2011-07-21 10:00 AM (UTC-5)

No surprises here. This is the expected behavior.

2. Full ISO datetime without `Z`

This is where things could go wrong, but don’t—at least not yet. Both functions interpret the string as local time and keep the value as-is. It is as well by ISO 8601 standard. When the timezone offset or Z is omitted, the datetime is considered local or unspecified—it doesn’t explicitly represent UTC or any other timezone.

const iso = '2011-07-21T15:00:00';

In EST, you get:

2011-07-21 3:00 PM (local time)

There’s no UTC conversion happening here. It’s assumed the string represents a local time, so both parsers comply and don’t shift anything. All good.

3. Date-only strings (no time component)

And here’s the twist. With a plain date like this:

const dateOnly = '2011-11-11';

parseISO(dateOnly) → Nov 11, 2011, 12:00 AM local time
new Date(dateOnly) → Nov 10, 2011, 7:00 PM EST

Wait—what?

new Date(str) interprets this string as midnight UTC, then converts it to local time. So if you’re in UTC-5, you get pushed back to the previous day. Meanwhile, parseISO(str) treats it as local time from the start, which is much more intuitive in most cases and seems to be closer to the ISO 8601 standard. Explicit presence of time zone information is required so the date string is treated not in local time zone.

A Case for Consistency

If you’re working with ISO strings and care about consistent behavior across time zones (and you should), you need to think about both ends: not just how you read dates from storage, but how you write them too.

If your goal is to treat stored datetimes as absolute moments in time, make sure your ISO strings end with a Z. That tells JavaScript (and pretty much every parser) that this value is in UTC—no ambiguity, no surprises.

As for date-only strings? Handle them with care. parseISO(str) from date-fns treats them as local time—so 2011-11-11 becomes midnight in the user’s local zone, with no unexpected shifts. new Date(str) on the other hand interprets them as midnight UTC, which means your “safe” date could silently land on the previous day if your user is west of Greenwich.

Mirror of this article on my personal site.

Sticky header with dynamic shadow using tailwind

Michael Musatov — Fri, 17 May 2024 06:18:19 +0000

Implementing sticky header with shadow

Recently, I had fun experimenting with styles by implementing a sticky header. Making a header sticky is fairly straightforward, but adding a shadow that only appears when the header becomes sticky introduces a delightful challenge. This makes the task much more interesting and non-trivial.

Creating the Boilerplate Project

For this project, I'm opting to use NextJS with pnpm, which is a fast and disk space-efficient package manager. You can read more about why one might choose pnpm over other package managers here.

To get started, create a new NextJS project by running:



pnpm create next-app

After setting up the project, remove any unused code to keep things tidy. Next, prepare a card component that will help emulate scrollable content. This component will serve as a practical demonstration of the sticky header as you scroll. All the changes can be found in the repository.

Implementing the Header

Creating a sticky header in Tailwind CSS is quite straightforward. Let's encapsulate this functionality within a dedicated component:



export const StickyHeader: FC<{ title: string }> = ({ title }) => (
  <h1 className="bg-slate-100 sticky top-0 w-full p-4 text-center">{title}</h1>
);

This component uses Tailwind CSS classes to make the header sticky, ensuring it stays at the top as you scroll by applying top-0.

It works. However, an issue arises where cards beneath the header seem to disappear abruptly as they pass under it. To address this visual glitch, it would be beneficial to add a border or shadow at the bottom of the sticky header to delineate it from the content below once it becomes fixed to the top. This adjustment will lead us into the more complex aspects of our implementation.

There is no straightforward CSS-only way to detect when the header becomes sticky, but we can use a small hack to achieve desired behavior.

Lets start from adding the shadow.



export const StickyHeader: FC<{ title: string }> = ({ title }) => (
  <h1 className="bg-slate-100 sticky top-0 w-full p-4 text-center text-lg shadow">
    {title}
  </h1>
);

And here is the result:

A shadow added around the entire header using Tailwind CSS's shadow class. Initially, this seems like a solution, but it introduces new problems, as you can see in the animation above:

The shadow appears around the entire header, not just at the bottom.
The shadow is always visible, not only when the header is sticky.

Let’s address these issues one by one to refine our header's behavior.

Shadow Only to the Bottom

Tailwind CSS doesn’t provide predefined classes for applying shadows to specific sides of an element. However, we can use arbitrary values within Tailwind classes, custom css classes or extend Tailwind's theme to include custom styles. For production environments, extending the theme is often preferred. This approach takes advantage of Tailwind’s Just-in-Time (JIT) compiler, which generates CSS only for the classes used, optimizing performance and keeps them reusable unlike usage arbitrary values.

Here's how you can extend the theme to include a custom class shadow-b for bottom-only shadows:



const config: Config = {
    ...
    theme: {
        ...
        boxShadow: {
            ...
            b: "0 5px 8px -1px rgba(0, 0, 0, 0.1)",
            ...
        },
    },
    ...
};

Apply this new shadow style to our header (Shadow changed from shadow to shadow-b):



export const StickyHeader: FC<{ title: string }> = ({ title }) => (
  <h1 className="bg-slate-100 shadow-b sticky top-0 w-full p-4 text-center text-lg">
    {title}
  </h1>
);

Checking the result:

After applying the custom shadow, the visual results show the shadow only at the bottom of the header, aligning more closely with our design goals. However, the shadow is still visible from the start, not just when the header is sticky. Our next step is to tackle this issue, ensuring the shadow appears only when needed.

Hide the Shadow and Display When Sticks

To control the visibility of the shadow only when the header is sticky, we can employ a clever CSS trick: overlaying an invisible element with a higher z-index right above the shadow. This method effectively hides the shadow under normal circumstances and only reveals it when the header sticks to the top.

Here's how we implement it:



export const StickyHeader: FC<{ title: string }> = ({ title }) => (
  <>
    <h1 className="bg-slate-100 shadow-b sticky top-0 w-full p-4 text-center text-lg">
      {title}
    </h1>
    <div className="bg-slate-100 z-10 -mt-4 h-2 w-full" />
  </>
);

The div is placed to overlap the shadow using negative margin (-mt-4). This setup ensures that the shadow is invisible until the header becomes sticky.

After implementing this method, the shadow behaves as intended.

However, a nasty visual artifact arises: the element used to hide the shadow partially overlaps the header's text during scrolling when the header is sticky, as shown in the animation.

To address this new challenge, we need to refine our approach so that the text remains unobstructed while maintaining the shadow effect.

Fixing UI bug

To resolve the overlapping issue, we adjusted the structure and z-index of our elements. By separating the shadow from the header and setting proper z-index values, we can keep the shadow visible only when needed, without overlapping element interfering with the header text.

Here’s the updated component:



export const StickyHeader: FC<{ title: string }> = ({ title }) => (
  <>
    <h1 className="bg-slate-100 sticky top-0 -mb-4 w-full p-4 text-center text-lg">
      {title}
    </h1>
    <div className="shadow-b sticky top-[52px] h-2 w-full" />
    <div className="bg-slate-100 z-10 -mt-4 h-2 w-full" />
  </>
);

In this setup:

The -mb-4 margin adjustment on the header compensates for the space taken by additional elements.
The shadow is now on a separate div that is positioned just below the header. The sticky top-[52px] positioning ensures it remains in place as you scroll.
A third div, also is not sticky but with higher z-index than shadow, so it covers the shadow when the header is not at the top, preventing it from showing prematurely.

With these changes, the shadow now appears correctly only when the header sticks to the top, and no part of the header text is obscured during scrolling. Here’s how it looks in action:

This final adjustment effectively resolves the visual glitch and achieves the desired effect with a clean, functional UI.

Summary

In this tutorial, we detailed how to implement a sticky header with a dynamic shadow using Tailwind CSS. The solution ensures a seamless shadow appearance as the header transitions to a fixed position. It worked for me for both web and hybrid applications. Though I will be happy to know about other approaches.

Conditional Rendering in React with a Switch Component

Michael Musatov — Wed, 18 Oct 2023 14:25:25 +0000

Controlling the rendering of UI elements based on certain conditions is a common task in web development. There are plenty of methods to accomplish this in React, and in this article, I'll show you how to create a simple component that does it in a declarative way.

Let's begin by setting up a React project. In this guide, I'll be using Vite, but it's important to note that for the purpose of this article, all the options, such as CRA (Create React App), Next.js, Remix, and more, are equally good.

Creating boilerplate project

With Vite it is pretty straightforward. Lets create it with the following command:

yarn create vite

Then just follow the master instructions. The only note, I'd like to use Typescript here.

After creating a project (I've named it react-switch) the dependencies need to be installed with

cd ../react-switch
yarn

Validate boilerplate by running dev server with the following command:

yarn dev

and opening the link in the browser http://127.0.0.1:5173/. Simple and beauty Vite + React boilerplate will be shown.

And then cleanup unnecessary code and resources from the project

Remove unnecessary code from App.tsx component to get it to the following state:

import './App.css'

function App() {
  return (
    <>
      <h3>React Switch Component</h3>
    </>
  )
}

export default App

Remove most of the styles for App.css and keep only the following:

#root {
  max-width: 1280px;
  margin: 0 auto;
  padding: 2rem;
  text-align: center;
}

Beside that the following files can be removed:
- src/assets/react.svg
- public/vite.svg

The never type is used here. It represents the value which will never occur. The full info in the specification https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#the-never-type

Also we will add empty Switch.tsx file for our future Switch component in the src directory.

Switch component implementation

The component should have the structure like below when user.

<Switch condition={<condition>}>
  <Switch.Case when={<possible-value>}>
  ...
  </Switch.Case>
  <Switch.Default>
  ...
  </Switch.Default>
</Switch>

We’re importing functional component (FC), ReactElement, and ReactNode from 'react'. These types are foundational to the Switch component, ensuring type safety and clarity in its usage.

import { FC, ReactElement, ReactNode } from 'react'

Define the Case and Default Props. CaseProps and DefaultProps interfaces for the Case and Default elements respectively. CaseProps takes children and a when prop, which can be a string or a number (which is always possible to adjust to your specific case). DefaultProps, on the other hand, only accepts children - the when prop is set to never, ensuring it's not used with the Default component.

interface CaseProps {
  children?: ReactNode
  when: string | number
}

interface DefaultProps {
  children?: ReactNode
  when?: never
}

We need one more interface which outlines the props for the main Switch component. It should accept a condition prop, which determines which Case component to render, and the children prop which could be a single or an array of ReactElement.

interface SwitchComponentType extends FC<SwitchComponentProps> {
  Case: FC<CaseProps>
  Default: FC<DefaultProps>
}

We extend the FC type to declare the Switch component along with its nested Case and Default components. This architecture simplifies the usage syntax, making it more intuitive.

Implementation of Case and Default elements is straightforward. The main goal is to provide a wrapper for components which will be possible rendered.

Switch.Case = ({ children }) => {
  return <>{children}</>
}

Switch.Default = ({ children }) => {
  return <>{children}</>
}

Now lets craft the Switch component itself. This is the place where the magic happens. It processes the children props to find the matching Case component based on the condition prop or returns the Default component if no match is found.

export const Switch: SwitchComponentType = ({ condition, children }) => {
  if (!children) {
    return null
  }

  const arrayOfChildren = Array.isArray(children) ? children : [children]
  const cases = arrayOfChildren.filter((child) => child.props.when == condition)
  const defaultCases = arrayOfChildren.filter((child) => !child.props.when)

  if (defaultCases.length > 1) { 
    throw new Error('Only one <Switch.Default> is allowed')
  }

  const defaultCase = defaultCases[0]

  return cases.length > 0 ? <>{cases}</> : <>{defaultCase}</>
}

Lets break it down.

Basically as a first step we check if there are any children in our Switch component. It should not render anything if children are absent.

if (!children) {
  return null
}

Next line creates an arrayOfChildren. It checks if the children prop is an array. If it's an array, arrayOfChildren is set to children. If it's not an array (i.e., there's only a single child), it wraps that child in an array, making it easier to work with later in the code.

const arrayOfChildren = Array.isArray(children) ? children : [children]

As a next step we create cases array that will contain child components whose when prop matches the provided condition. The filter method is used to iterate through each child component and select only those where the when prop is equal to the provided condition.

const cases = arrayOfChildren.filter((child) => child.props.when == condition);

We also need to create defaultCases array which contains child components with no when prop defined. In this filter function, it selects child components where the when prop is falsy or undefined.

Then do the check ensures that there is at most one <Switch.Default> component. If there are multiple default cases (i.e., multiple components without a when prop), it throws an error to indicate that only one <Switch.Default> component is allowed within a Switch.

And assign defaultCase with either undefined or first and only element of defaultCases array.

const defaultCases = arrayOfChildren.filter((child) => !child.props.when);
if (defaultCases.length > 1) { 
  throw new Error('Only one <Switch.Default> is allowed');
}
const defaultCase = defaultCases[0];

Finally, the last piece of code (provided below) determines what to render based on the cases and defaultCase. If there are matching cases (i.e., cases.length > 0), it returns the components. If there are no matching cases, it returns the defaultCase component, or null if there's no defaultCase.

return cases.length > 0 ? <>{cases}</> : <>{defaultCase}</>;

Switch component usage

We are suing Switch component inside App component. The full code of updated App component is below.

import { useState } from 'react'
import './App.css'
import { Switch } from './Switch'

function App() {
  const [condition, setCondition] = useState<undefined | string>()

  return (
    <>
      <h3>React Switch Component</h3>

      <div className='field-container'>
        <label className='label' htmlFor="select-input">Possible values:</label>
        <select id="select-input" onChange={(e) => setCondition(e.target?.value)}>
          <option>Not defined</option>
          <option value="1">1</option>
          <option value="2">2</option>
        </select>
      </div>

      <div className='switch-section-container'>
        <div className='label'>Possible values:</div>
        <Switch condition={condition}>
          <Switch.Case when={1}>
            <div className="case-item">1</div>
          </Switch.Case>
          <Switch.Case when={2}>
            <div className="case-item">2</div>
          </Switch.Case>
          <Switch.Default>
            <div className="case-item">Default</div>
          </Switch.Default>
        </Switch>
      </div>
    </>
  )
}

export default App

Lets review the changes line by line.

To demonstrate a usage and test our Switch component lets import it to the App.tsx

import { Switch } from './Switch'

Also to change and check conditions we should add some state to the App component

const [condition, setCondition] = useState<undefined | string>()

This state is modified by a select element.

<select id="select-input" onChange={(e) => setCondition(e.target?.value)}>
  <option>Not defined</option>
  <option value="1">1</option>
  <option value="2">2</option>
</select>

And used to conditionally display different cases content with our newly created Switch component.

<Switch condition={condition}>
  <Switch.Case when={1}>
    <div className="case-item">1</div>
  </Switch.Case>
  <Switch.Case when={2}>
    <div className="case-item">2</div>
  </Switch.Case>
  <Switch.Default>
    <div className="case-item">Default</div>
  </Switch.Default>
</Switch>

Conclusion

In summary, the Switch component we've created allows a cleaner and more expressive way to handle conditional rendering in React, similar to a switch-case statement. It filters and renders child components based on the provided condition, providing a more intuitive and readable approach to conditional rendering in React applications. While it can be used as-is, it primarily serves as an example of creating conditional rendering components in React.

The complete source code is accessible on GitHub at this link, and it can be explored interactively using StackBlitz at this link.

Mirror of this article on my personal site.

Improving Code Coverage Reporting in Monorepos

Michael Musatov — Mon, 22 May 2023 16:32:46 +0000

Tracking code coverage is an essential aspect of maintaining the health and robustness of a software project. However, this task becomes more challenging when using a monorepo, where multiple applications and packages coexist within a single repository. Despite the multitude of available tools, I found it impossible to create a simple report for our weekly reviews. This article outlines a method to streamline code coverage reporting in a monorepo setup using Node.js, aiming to produce an easily interpretable summary report.

The ultimate goal is to have a straightforward, console-friendly table output in the following format:

(index)	lines	statements	functions	branches
total	---	---	---	---
app1	---	---	---	---
app2	---	---	---	---
package1	---	---	---	---
package2	---	---	---	---

Let's break down the process of achieving this.

NOTE: Please remember that this code was developed with a specific objective and a precise Turborepo structure. Although it could be generalized, I currently have no immediate need for such modifications.

Prerequisites

The repository should already have unit testing with jest configured for individual packages and applications.

Process Overview

The process of creating this summary report involves the following steps:

Configuring TurboRepo to collect coverage in JSON format per package or application. This will result in a coverage-summary.json file in the coverage folder of each package.
Writing a script to collate these coverage summaries. The script will:
1. Identify all application and package directories,
2. Retrieve paths to all the summary files, and
3. Generate a combined JSON file representing both individual and total coverage.
Rendering the collected data in a console-friendly table.

Configuration changes

First of all we should create coverage reports for every single package and application in the repository. To do so, we should have proper jest.config.ts files for them at the first place. The coverageReport property should be added:

  "coverageReporters": ["json"]

NOTE: You can have a huge variety of the report formats listed in the array, but for this article only json is needed

Moreover, the package.json file for each package should be configured with the following task:

  "coverage": "jest --coverage"

To verify we have the reporting working we should run the following command for individual package/application.

yarn coverage

Than take a look a the new directory coverage created in the directory from which you've run the command above. It should contain the file called coverage-summary.json.

NOTE: I'm using yarn, but it will just as good with npm run

The next step will be to configure the project to run command above for each package and application. I'm using turborepo for managing mono repository. It has configuration file turbo.json at which I should add just a single line

  "coverage": {
    "dependsOn": ["^build"]
  },

As the result, I can run turbo run coverage command which will trigger coverage calculation for each application and package.

The only component we're missing is the script that collects all the coverage reports and creates a summary. Let's name the script like this monoRepoTotalCoverage.js NOTE: Details are covered in the section below. It's executable with node monoRepoTotalCoverage.js command.

For the sake of simplicity it would be nice to have yarn/npm tasks in package.json to make preparation of summary report a single line command.

"scripts": {
  ...
  "coverage:per-package": "turbo run coverage",
  "coverage:total": "yarn coverage:per-package && node coverage-total.js",
  ...
}

The only needed command now is yarn coverage:total.

Script review

The script involves several stages and performs the following functions:

Collect Paths to Coverage Summaries: The script navigates through the directories of all applications and packages within the monorepo, assembling paths to each package's coverage-summary.json file.

function getAllPathsForPackagesSummaries() {
  const getDirectories = (source) =>
    fs
      .readdirSync(source, { withFileTypes: true })
      .filter((dirent) => dirent.isDirectory())
      .map((dirent) => dirent.name)

  const appsPath = path.join(_dirname, 'apps')
  const appsNames = getDirectories(appsPath)

  const appsSummaries = appsNames.reduce((summary, appName) => {
    return {
      ...summary,
      [appName]: path.join(appsPath, appName, 'coverage', 'coverage-summary.json'),
    }
  }, {})

  const packagesPath = path.join(_dirname, 'packages')
  const packageNames = getDirectories(packagesPath)

  const packagesSummaries = packageNames.reduce((summary, packageName) => {
    return {
      ...summary,
      [packageName]: path.join(packagesPath, packageName, 'coverage', 'coverage-summary.json'),
    }
  }, {})

  return { ...appsSummaries, ...packagesSummaries }
}

Generate Consolidated Coverage Report: Each package's coverage-summary.json file is read, and the coverage statistics are aggregated into a unified summary report. This provides a consolidated view of the total code coverage across the monorepo.

function readSummaryPerPackageAndCreateJoinedSummaryReportWithTotal(packagesSummaryPaths) {
  return Object.keys(packagesSummaryPaths).reduce(
    (summary, packageName) => {
      const reportPath = packagesSummaryPaths[packageName]
      if (fs.existsSync(reportPath)) {
        const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'))

        const { total } = summary

        Object.keys(report.total).forEach((key) => {
          if (total[key]) {
            total[key].total += report.total[key].total
            total[key].covered += report.total[key].covered
            total[key].skipped += report.total[key].skipped
            total[key].pct = Number(((total[key].covered / total[key].total) * 100).toFixed(2))
          } else {
            total[key] = { ...report.total[key] }
          }
        })
        return { ...summary, [packageName]: report.total, total }
      }

      return summary
    },
    { total: {} },
  )
}

Format Report for Visual Presentation: The script transforms the coverage report into a console-friendly format, appending the percentage difference next to the current coverage if a comparison with a previous report was made.

function createCoverageReportForVisualRepresentation(coverageReport) {
  return Object.keys(coverageReport).reduce((report, packageName) => {
    const { lines, statements, functions, branches } = coverageReport[packageName]
    return {
      ...report,
      [packageName]: {
        lines: lines.pct,
        statements: statements.pct,
        functions: functions.pct,
        branches: branches.pct
      },
    }
  }, {})
}

Print the report: The final coverage report is printed to the console in an easy-to-read table format.

console.table(coverageReportForVisualRepresentation)

The final execution script, built from the functions mentioned above, is as follows:

// Execution Stages
// 1. Read all coverage-total.json files
const packagesSummaryPaths = getAllPathsForPackagesSummaries()
// 2. Generate consolidated report
const currCoverageReport =
  readSummaryPerPackageAndCreateJoinedSummaryReportWithTotal(packagesSummaryPaths)
// 3. Reformat the report for visual representation
const coverageReportForVisualRepresentation =
  createCoverageReportForVisualRepresentation(currCoverageReport)
// 4. Print the report
console.table(coverageReportForVisualRepresentation)

This script will produce an easy-to-read table in the console as output:

(index)	lines	statements	functions	branches
total	'85.88'	'85.18'	'78.64'	'78.45'
app1	'17.04'	'17.40'	'20.56'	'24.19'
app2	'87.93'	'86.78'	'79.66'	'77.95'
package1	'96.67'	'97.06'	'94.59'	'81.16'
package2	'100.00'	'100.00'	'100.00'	'100.00'

While the current coverage report offers valuable insights, there's potential for improvement. Specifically, it would be beneficial to contrast current data with previous reports. To achieve this, we need to implement the following improvements:

Ensure result persistence
Enable loading of previous results
Introduce a function for calculating differences
Revise the function that prepares visual representation to exhibit these differences.

Delineating Differences with Previous Results

Let's implement saving of the report for future usage. It can be done the following way:

function writeCoverageReportToFile(coverageReport) {
  function createDateTimeSuffix() {
    const date = new Date()
    return `${date.getFullYear()}-${
      date.getMonth() + 1
    }-${date.getDate()}_${date.getHours()}-${date.getMinutes()}`
  }

  const dir = path.join(_dirname, 'coverage')

  if (!fs.existsSync(dir)) {
    fs.mkdirSync(dir)
  }

  fs.writeFileSync(
    `coverage/coverage-total.${createDateTimeSuffix()}.json`,
    JSON.stringify(coverageReport, null, 2),
  )
}

Loading of the previous report is also straight forward. We will pass the path to the previous report as parameter.

like this:

yarn coverage:total coverage/coverage-total.2023-5-17_15-30.json

And the implementation in the script will be the following:

// Params
const pathToPreviousReport = process.argv[2]

/**
 * Reads the coverage-summary.{XXX}.json file and returns the parsed JSON object
 * @param {*} pathToReport
 * @returns
 */
function readPreviousCoverageSummary(pathToReport) {
  if (!pathToReport) {
    console.warn('Previous coverage results were not provided.')
    return
  }
  // Read the JSON file
  const prevCoverage = JSON.parse(fs.readFileSync(pathToReport, 'utf8'))
  return prevCoverage
}

Now we need to calculate the difference between current and previous report. Let's do it that way:

function creteDiffCoverageReport(currCoverage, prevCoverage = {}) {
  return Object.keys(currCoverage).reduce((summary, packageName) => {
    const currPackageCoverage = currCoverage[packageName]
    const prevPackageCoverage = prevCoverage[packageName]
    if (prevPackageCoverage) {
      const coverageKeys = ['lines', 'statements', 'functions', 'branches']
      coverageKeys.forEach((key) => {
        const prevPct = prevPackageCoverage[key]?.pct || 0
        const currPct = currPackageCoverage[key]?.pct || 0

        currPackageCoverage[key] = {
          ...currPackageCoverage[key],
          pctDiff: (parseFloat(currPct) - parseFloat(prevPct)).toFixed(2),
        }
      })
    }
    return { ...summary, [packageName]: currPackageCoverage }
  }, {})
}

And the last thing to improve is to update the output table with the difference between current and previous report.

function formatPtcWithDiff(ptc, ptcDiff) {
  return appendDiff(formatDecimal(ptc), ptcDiff && formatDecimal(ptcDiff))
}

function formatDecimal(ptc) {
  return parseFloat(ptc).toFixed(2)
}

function appendDiff(ptc, ptcDiff) {
  if (!ptcDiff || ptcDiff === ptc) {
    return ptc
  }
  return `${ptc} (${ptcDiff > 0 ? '+' : ''}${ptcDiff}%)`
}

/**
 * Takes the coverage report and returns an object with the
 * coverage for each package and the total coverage suitable
 * for the visual representation in a console table
 * @param {*} coverageReport
 * @returns
 * */
function createCoverageReportForVisualRepresentation(coverageReport) {
  return Object.keys(coverageReport).reduce((report, packageName) => {
    const { lines, statements, functions, branches } = coverageReport[packageName]
    return {
      ...report,
      [packageName]: {
        lines: formatPtcWithDiff(lines.pct, lines.pctDiff),
        statements: formatPtcWithDiff(statements.pct, statements.pctDiff),
        functions: formatPtcWithDiff(functions.pct, functions.pctDiff),
        branches: formatPtcWithDiff(branches.pct, branches.pctDiff),
      },
    }
  }, {})
}

The final report table with coverage changes will look like this:

(index)	lines	statements	functions	branches
total	'87.84 (+1.96%)'	'87.11 (+1.93%)'	'78.95 (+0.31%)'	'79.53 (+1.04%)'
app1	'58.13 (+41.09%)'	'56.78 (+39.38%)'	'31.93 (+11.37%)'	'44.78 (+20.59%)'
app2	'87.34 (-0.59%)'	'86.09 (-0.69%)'	'78.30 (-1.36%)'	'78.85 (+0.90%)'
package1	'96.67 (0.00%)'	'97.06 (0.00%)'	'94.59 (0.00%)'	'81.16 (0.00%)'
package2	'100.00 (0.00%)'	'100.00 (0.00%)'	'100.00 (0.00%)'	'100.00 (0.00%)'

Conclusion

In summary, this article showed how to improve the process of tracking and visualizing Jest coverage reports across monorepos. The provided script creates a handy coverage table and, while tailored to a specific Turborepo structure, can be adapted for different projects. You can find the complete script in this GitHub Gist.

Angular Forms Validation: Part III - Async Validators gotchas

Michael Musatov — Thu, 26 Mar 2020 06:25:11 +0000

I am about to continue sharing my expertise on Angular's Forms Validation. In this forthcoming article, we will examine common pitfalls and challenges that arise when utilizing async validators.

I. Absence of Error Message in UI after Async Validation Completion

This is a common issue that many developers encounter when working with async validators. Interestingly, it has been an open issue on the Angular GitHub repository for over three and a half years. This problem is not limited to just the OnPush change detection strategy but also affects the Default strategy. Let's explore a scenario where you are likely to encounter this problem.

To demonstrate the issue, let's declare a simple component with the Default change detection strategy:



@Component({...})
export class SingleControlComponent {
  readonly usernameControl = new FormControl(null, 
    { asyncValidators: userDoesNotExist, updateOn: 'blur' });
}

function userDoesNotExist(control: FormControl): Observable<ValidationErrors | null> {
  console.log('Starting async validation...')
  const result$ = control.value !== 'test'
    // 'delay' is used to simulate server call
    ? of({'user-does-not-exist': true}).pipe(delay(1000))
    : of(null).pipe(delay(1000));

  return result$.pipe(tap(result => console.log(result)));
}

The component consists of a single FormControl with an Async Validator function that emulates checking the availability of a username. The template markup for the component is as follows:



<label for="username">Username</label>
<input name="username" type="text" [formControl]="usernameControl">
<div class="errors">
  <span *ngIf="usernameControl.hasError('user-does-not-exist')">Username in not used</span> 
</div>

After executing this code, the following behavior can be observed:

What is going on here? Let's split it into stages

The user enters a valid value 'test', in the field and then moves the focus away from it. (NOTE: The updateOn: 'blur' configuration is used to prevent multiple validation calls.) Upon doing so, the console displays messages indicating the start and completion of the validation process without any errors. So far, everything is working as expected.
The user updates the value to an invalid one, such as 'test1'. Once again, messages about the start and completion of validation appear in the console. Since the validation fails, the console displays {user-does-not-exist: true}. However, at the UI level, no errors are displayed.
The user interacts with the field by focusing on it and then moving the focus away. This triggers a change detection, resulting in the UI being updated. (NOTE: In the case of the OnPush change detection strategy, change detection will not be triggered by this interaction, and the UI will remain in an outdated state. In such cases, manual triggering of change detection is necessary.)

Indeed, to address this issue, we need to explicitly inform Angular to run change detection when we have the validation result. Adding the following code snippet to our component will achieve precisely that:



...
constructor(cd: ChangeDetectorRef) {
  this.usernameControl.statusChanges.subscribe(() => cd.markForCheck());
}
...

Now, with the addition of the code snippet, the behavior aligns with our expectations, and the issue has been resolved:

II. Async Validators start simultaneously on parent and child

There are situations where we need to asynchronously validate not just the value of a single FormControl, but the entire FormGroup. Angular provides this functionality, but unfortunately, not everything goes as expected. Below, we will demonstrate two common problems that you are likely to encounter.

II.A Status of the parent not updated as expected

In some cases, when performing async validation, we may want to show a progress indication or lock form controls in the UI to inform the user. Angular's AbstractFormControl (and his descendants FormControl and FormGroup) provides a useful observable property for such scenarios: statusChanges. The value of this property becomes PENDING when an async validation is in progress. Let's take a look at a demo for this scenario.

Here we have a simple component with a FormGroup and an async validator applied to the group.



...
Component({...})
export class ParentChildStatusComponent {
  constructor() { 
    this.form = new FormGroup({
      'username': new FormControl(null, [Validators.required]),
      'password': new FormControl(null, [])
    }, { updateOn: 'blur', asyncValidators: this.passwordAlreadyUsed.bind(this) });
  }

  private passwordAlreadyUsed(control: FormGroup): Observable<ValidationErrors | null> { ... }
}

NOTE: Some code related to displaying the validation progress has been omitted for simplicity.

The markup for this component is as follows:



<div class="form" [formGroup]="form">
  <label for="username">Username</label>
  <input name="username" type="text" formControlName="username">
  <div class="errors">
    <span *ngIf="form.get('username').hasError('required')">Username is Required</span> 
  </div>
  <label for="password">Password</label>
  <input name="password" type="text" formControlName="password">
  <div class="progress validator">USERNAME ASYNC VALIDATOR STATUS: {{usernameValidatorStatus$ | async}}</div>
  <div class="progress validator">PASSWORD ASYNC VALIDATOR STATUS: {{passwordValidatorStatus$ | async}}</div>
  <div class="progress">FORM STATUS IS {{(form.statusChanges | async) || form.status}}</div>
</div>

Let's take a look at the output during the execution of this demo:

The form has a single synchronous validator (Validators.required) applied to the 'username' FormControl. Initially, the form is in the 'INVALID' state and no asynchronous validators are running or executed.
The user enters a value in the username field and then moves the focus away from it (the form has the updateOn: 'blur' option set). After that, the synchronous validator is executed, and the result is valid. Then, the asynchronous validator of the FormGroup starts executing, and the FormGroup's status becomes PENDING . The validator is in the STARTED state.
Once the validation is completed, the FormGroup's status becomes VALID. Everything is progressing smoothly and exactly as expected.

Now, let's add an additional asynchronous validator to the 'username' FormControl and observe how it affects the form's behavior.



...
Component({...})
export class ParentChildStatusComponent {
  constructor() { 
    this.form = new FormGroup({
      'username': new FormControl(null, [Validators.required], [this.userDoesNotExist.bind(this)]),
      'password': new FormControl(null, [])
    }, { updateOn: 'blur', asyncValidators: this.passwordAlreadyUsed.bind(this) });
  }

  private userDoesNotExist(control: FormControl): Observable<ValidationErrors | null> { ... }

  private passwordAlreadyUsed(control: FormGroup): Observable<ValidationErrors | null> { ... }
}

Let's examine the user interface of the form after incorporating this small enhancement in form validation.

Although the user interface appears similar, we have encountered a problem in the form validation.

Initially, the form is in an INVALID state with no asynchronous validators running or executed.
When the user enters a value in the username field and moves the focus away, the synchronous validator completes. After that, both the asynchronous validator of the 'username' FormControl and the asynchronous validator of the FormGroup start executing. As a result, the FormGroup status becomes PENDING and both validators are indicated as STARTED in the console. So far so good.
However, after the validation for the 'username' FormControl is completed and the FormGroup status changes to VALID, we encounter an issue. The asynchronous validator of the FormGroup is still running, which leads to an incorrect status for the form. Consequently, we cannot rely on the form status for locking the user interface or displaying progress indications. This is a disappointing discovery.

Therefore, the current status of the form is incorrect, and we cannot depend on it for locking the user interface or displaying progress indications. This limitation is indeed disappointing, as it hinders our ability to provide accurate feedback to the user.

II.B A synchronous validator failure does not prevent async validator from triggering

Let's take a look at another example of async validator problems. This one is going to be the last one, but definitely not the least. Suppose we want to make the password field required in our password setting form. We can achieve this by applying the Validators.required validator to the 'password' FormContorl.



...
Component({...})
export class ParentChildStatusComponent {
  constructor() { 
    this.form = new FormGroup({
      'username': new FormControl(null, [Validators.required], [this.userDoesNotExist.bind(this)]),
      'password': new FormControl(null, [Validators.required])
    }, { updateOn: 'blur', asyncValidators: this.passwordAlreadyUsed.bind(this) });
  }

  private userDoesNotExist(control: FormControl): Observable<ValidationErrors | null> { ... }

  private passwordAlreadyUsed(control: FormGroup): Observable<ValidationErrors | null> { ... }
}

And now we expect the passwordAlreadyUsed async validator to be executed only after all sync validators have passed. This behavior is explicitly mentioned in Angular's documentation:

It is important to note that the asynchronous validation happens after the synchronous validation, and is performed only if the synchronous validation is successful. This check allows forms to avoid potentially expensive async validation processes such as an HTTP request if more basic validation methods fail.

However, the form validation behaves differently in this case.

The form goes through the following stages:

The form is initially in an INVALID state , and no async validators are running or executed.
The user edits the 'username' field and moves the focus away from it. The synchronous validation successfully completes, and then the asynchronous validator for this control starts executing.
However, something unexpected happens. The asynchronous validator passwordAlreadyUsed starts running! , even though the 'password' FormControl is invalid.

After the user fills out the form and all the validations are completed, the resulting form state is correct. However, we notice that there are unnecessary calls to the server due to the unexpected execution of the passwordAlreadyUsed async validator.

Angular's documentation likely meant the order of execution for sync and async validators for the same FormControl or FormGroup. However, in this case, we have a hierarchy of validators that seems to unexpectedly deviate.

Conclusion

Thank you for reading. I hope this article has provided you with valuable insights and saved you time in understanding how Angular's forms behave. It's important to note that while the actual behavior may differ from what you expect, understanding these nuances will help you work more effectively with Angular's forms. You can find all the code samples used in this article at the following location Github. If you have any questions or need further clarification, feel free to reach out. Happy coding!

Links to the previous articles:
Angular Forms Validation: Part I - Single control validation.
Angular Forms Validation: Part II - FormGroup validation.

Angular Forms Validation: Part II - FormGroup Validation

Michael Musatov — Sun, 02 Feb 2020 13:47:06 +0000

I've recently embarked on a journey to document my experiences with Angular development, with a special emphasis on validation. The first part of this series can be found here. Today, I'll be expanding on this topic, focusing specifically on FormGroup validation and the validation of dependent controls.

Example: Password Confirmation Form

As is customary, let's begin with the code. Below, you will find the declaration of the password confirmation form model. We've applied some Validators provided by Angular to the fields.



this. Form = new FormGroup({
  'email': new FormControl(null, [Validators.required, Validators.email]),
  'password': new FormControl(null, [Validators.required]),
  'confirmation': new FormControl(null, [Validators.required])
});

Html markup with Angular bindings



<div class="form" [formGroup]="form">
  <label for="email">Email</label>
  <input name="email" type="text" formControlName="email">
  <div class="errors">
    <span *ngIf="form.get('email').hasError('required')">Email is Required</span> 
    <span *ngIf="form.get('email').hasError('email')">Email is mailformed</span> 
  </div>
  <label for="password">Password</label>
  <input name="password" type="password" formControlName="password">
  <div class="errors">
    <span *ngIf="form.get('password').hasError('required')">Password is Required</span>
  </div>
  <label for="confirmation">Password Confirmation</label>
  <input name="confirmation" type="password" formControlName="confirmation">
  <div class="errors">
    <span *ngIf="form.get('confirmation').hasError('required')">Password confirmation is Required</span> 
  </div>
  <button [disabled]="!form.valid" type="submit">SUBMIT</button>
</div>

The code should yield results similar to those demonstrated in the GIF below:

Everything is functioning quite well, thanks to Angular! However, we're still missing some crucial features. For example, we aren't checking if the password and confirmation match. Let's address this.

Implementing FormGroup Validator

We have the flexibility to apply Validators not only to FormControl but also to all descendants of AbstractFormControl, including FormGroup or FormArray. To implement a check that verifies a match between the password and its confirmation, we'll need a custom validator for the FormGroup. Below, you'll see the implementation of this validator.



function passwordConfirmationMissmatch(control: FormGroup): ValidationErrors | null {
  const password = control.get('password');
  const confirmation = control.get('confirmation');
  if (!password || !confirmation || password.value === confirmation.value) {
    return null;
  }

  return { 'password-confirmation-mismatch': true };
}

NOTE: The validator's implementation is specifically designed with the form group structure in mind, so it is not suitable for general use, unfortunately.

With our validator ready, it's time to incorporate it into our form.



this. Form = new FormGroup({
    ...
}, [passwordConfirmationMissmatch]);

And the validation results should be incorporated into the markup.



<div class="form" [formGroup]="form">
  ...
  <div class="form-errors-summary"> 
    <div *ngIf="form.hasError('password-confirmation-mismatch')">Password confirmation does not match the password</div>
  </div>
  <button [disabled]="!form.valid" type="submit">SUBMIT</button>
</div>

The result of our enhancements can be seen here.

This improvement is quite significant and sufficient for many cases. However, sometimes we need to validate our form against server-side data, and this is where asynchronous validators come into play.

Implementing a FormGroup Async Validator

In the case of our password setting form, it would be beneficial to check if the provided password has already been used with the given email. Let's proceed with implementing an asynchronous validator for this scenario and applying it to the FormGroup.



function passwordMustBeDifferentFromThePrevious(control: FormGroup): Observable<ValidationErrors | null> {
  const email = control.get('email');
  const password = control.get('password');
  const confirmation = control.get('confirmation');
  if (!email || !password || !confirmation) {
    return null;
  }

  return password.value === 'password' 
    // 'delay' is used to simulate server call
    ? of({'password-previously-used': true}).pipe(delay(2000))
    : of(null).pipe(delay(2000));
}

Now, let's apply the async validator to the FormGroup.



this. Form = new FormGroup({
    ...
}, [passwordConfirmationMissmatch], [passwordMustBeDifferentFromThePrevious]);

Additionally, let's utilize the validation result within the markup. It would also be helpful to visually indicate that the async validation is in progress by displaying the FormGroup's status as 'PENDING'.



<div class="form" [formGroup]="form">
  <div *ngIf="(form.statusChanges | async) === 'PENDING'" class="progress">VALIDATION IN PROGRESS</div>
  ...
  <div class="form-errors-summary"> 
    <div *ngIf="form.hasError('password-confirmation-mismatch')">Password confirmation does not match the password</div>
    <div *ngIf="form.hasError('password-previously-used')">Password was used already. Please select a different password.</div>
  </div>
  <button [disabled]="!form.valid" type="submit">SUBMIT</button>
</div>

Let's take a look at the user interface after implementing these changes.

As you can see, this covers most of what can be achieved with simple form validation. However, there are instances where we may need to highlight the fields that require changes to address FormGroup validation errors.

Highlighting FormGroup Validation Errors on the Controls

When using FormGroup validation, the error state is applied to the FormGroup itself, rather than the individual FormControls within it. As a result, all the FormControls are considered valid (which makes sense). However, what if we want to highlight the specific controls that require changes to address the validation errors? In our case, we want to highlight the password and password confirmation fields. To achieve this, let's enhance our validator and markup accordingly.



function passwordMustBeDifferentFromThePrevious(control: FormGroup): Observable<ValidationErrors | null> {
  const email = control.get('email');
  const password = control.get('password');
  const confirmation = control.get('confirmation');
  if (!email || !password || !confirmation) {
    return null;
  }

  const result$ = password.value === 'password' 
    // 'delay' is used to simulate server call
    ? of({'password-previously-used': true}).pipe(delay(2000))
    : of(null).pipe(delay(2000));

  return result$.pipe(
    tap(result => {
        if (result) {
          password.setErrors({...password.errors, ...result});
          confirmation.setErrors({...password.errors, ...result});
        } else if (password.errors) {
          const passwordErrors = { ...password.errors };
          delete passwordErrors['password-previously-used'];
          const confirmationErrors = { ...confirmation.errors };
          delete confirmationErrors['password-previously-used'];
        }
    })
  );  
}

NOTE: The code within the validator is responsible for setting the error state on specific controls ('password' and 'confirmation') while taking into account any other errors that may have already been set.

There are no changes required in the form declaration, but we do need to handle the 'password-previously-used' error for the 'password' and 'confirmation' controls within the markup.



<div class="form" [formGroup]="form">
  <label for="email">Email</label>
  <input name="email" type="text" formControlName="email">
  <div class="errors">
    <span *ngIf="form.get('email').hasError('required')">Email is Required</span> 
    <span *ngIf="form.get('email').hasError('email')">Email is mailformed</span> 
  </div>
  <label for="password">Password</label>
  <input name="password" type="password" formControlName="password">
  <div class="errors">
    <span *ngIf="form.get('password').hasError('required')">Password is Required</span>
    <span *ngIf="form.get('password').hasError('password-previously-used')">Password was previously used</span>
  </div>
  <label for="confirmation">Password Confirmation</label>
  <input name="confirmation" type="password" formControlName="confirmation">
  <div class="errors">
    <span *ngIf="form.get('confirmation').hasError('required')">Password confirmation is Required</span> 
    <span *ngIf="form.get('confirmation').hasError('password-previously-used')">Password was previously used</span>
  </div>
  <div class="form-errors-summary"> 
    <div *ngIf="form.hasError('password-confirmation-mismatch')">Password confirmation does not match the password</div>
    <div *ngIf="form.hasError('password-previously-used')">Password was used already. Please select a different password.</div>
  </div>
  <button [disabled]="!form.valid" type="submit">SUBMIT</button>
  <div *ngIf="(form.statusChanges | async) === 'PENDING'" class="progress">VALIDATION IS IN PROGRESS</div>
</div>

Let's take a look at how our complete validation works within the user interface.

Conclusion

Thank you for reading! I hope you found this information valuable and enjoyable. If you're interested, you can find all the code samples on Github.

There are two other articles available on the topic:
Angular forms validation. Part I. Single control validation.
Angular forms validation. Part III. Async Validators gotchas.

Angular Forms Validation: Part I - Single control validation

Michael Musatov — Fri, 17 Jan 2020 08:12:52 +0000

Angular offers powerful tools for managing forms. In this series of posts, I will discuss various Reactive Forms Validation examples, ranging from the simplest to more advanced ones.

In the first part of the series, we will focus on single form control validation. You can apply zero or any number of synchronous and asynchronous validators to a single control.

Let's start from the simplest possible example

A FormControl without validation, along with the Angular component markup to display this FormControl:



export class SingleControlComponent {
  readonly emailControl = new FormControl();
}



<label for="email">Email</label>
<input name="email" type="text" [formControl]="emailControl">

Running this example will yield the following results in the browser:

Adding synchronous validation to the FormControl

We are going to use validators provided by the Angular framework. Validators.required - requires to have a non-empty value. Validators.email - checking email against the pattern which is based on the definition of a valid email address in the WHATWG HTML specification with some enhancements to incorporate more RFC rules.



export class SingleControlComponent {
  readonly emailControl = new FormControl(null, [Validators.required, Validators.email]);
}

As the next step, we need to handle validation results in the control markup. The FormControl API is helpful here. The 'hasError' method checks for the presence of an error code ('required', 'email', etc.) in the control's errors collection.



<label for="email">Email</label>
<input name="email" type="text" [formControl]="emailControl">
<div class="errors">
  <span *ngIf="emailControl.hasError('required')">Email is Required</span> 
  <span *ngIf="emailControl.hasError('email')">Email is mailformed</span>
</div>

After making these changes, our control should work as shown in the following recording:

Implement asynchronous validator.

The next step will be implementing some asynchronous validation. Let's create an async validator that simulates checking for email presence on the server.



function emailMustNotBeUsed(control: AbstractControl): Observable<ValidationErrors | null> {
  return control.value === 'used@email.com' 
      ? of({'email-is-used': 'Email was used'}).pipe(delay(2000))
      : of(null).pipe(delay(2000));   
}

We're delaying the execution result to simulate a call to a remote resource. Now, we will add the async validator to the FormControl.



export class SingleControlComponent {
  readonly emailControl = new FormControl(null, 
    // Sync validators
    [Validators.required, Validators.email],
    // Async validator
    emailMustNotBeUsed);
}

Handling validator results in the component markup by adding the following element:



...
<span *ngIf="emailControl.hasError('email-is-used')">{{emailControl.getError('email-is-used')}}</span> 
...

Note: Error message from the validator is shown at the UI by using getError method. It can be helpfull if async validator return specific error message (received from the server for example).

The results of all our changes will be as shown in the recording below:

Validators execution order

The order of execution is guaranteed. First, all synchronous validators are executed in the order of declaration. Once synchronous validators return results and there are no errors, asynchronous validators are initiated. Asynchronous validators are initiated in the order of declaration, but the order of execution results is not guaranteed. Let's take a look at the code.



export class SingleControlComponent {
  readonly emailControl = new FormControl(null, 
    // Sync validators
    [Validators.required, Validators.email],
    // Async validators
    [emailMustNotBeUsed, emailIsForbidden]);
}

The implementation of asynchronous validators used for this form control is presented below:



function emailMustNotBeUsed(control: AbstractControl): Observable<ValidationErrors | null> {
  console.log('First async validator stars executing');
  const resutl$ = control.value === 'used@email.com' 
      ? of({'email-is-used': 'Email was used'}).pipe(delay(2000))
      : of(null).pipe(delay(2000));
  return resutl$.pipe(finalize(() => console.log('First async validator completed')));    
}

function emailIsForbidden(control: AbstractControl): Observable<ValidationErrors | null> {
  console.log('Second async validator stars executing');
  const resutl$ = control.value === 'forbidden@email.com' 
      ? of({'email-is-forbidden': 'Email was forbidden'}).pipe(delay(1500))
      : of(null).pipe(delay(1500));

  return resutl$.pipe(finalize(() => console.log('Second async validator completed')));    
}

The console output of running this sample will be exactly as follows:

First async validator stars executing
Second async validator stars executing
Second async validator completed
First async validator completed

The first two lines will always be printed in the same order, regardless of the internal async validator implementation. The order of the other two lines depends on the async validation delay.

Conclusion

Thank you for reading. I hope this information was helpful in some way. All code samples can be found on Github.

There are two other articles available on the topic:
Angular forms validation. Part II. FormGroup validation.
Angular forms validation. Part III. Async Validators gotchas.

DEV Community: Michael Musatov

A Toy Django REST API with an Admin Panel

The Python Environment setup

Django Setup

A toy API service

Conclusion

The Subtle Trap of ISO Date Strings in JavaScript

Where It All Begins

1. Full ISO datetime with ending Z

2. Full ISO datetime without Z

3. Date-only strings (no time component)

A Case for Consistency

Sticky header with dynamic shadow using tailwind

Implementing sticky header with shadow

Creating the Boilerplate Project

Implementing the Header

Shadow Only to the Bottom

Hide the Shadow and Display When Sticks

Fixing UI bug

Summary

Conditional Rendering in React with a Switch Component

Creating boilerplate project

Switch component implementation

Switch component usage

Conclusion

Improving Code Coverage Reporting in Monorepos

Prerequisites

Process Overview

Configuration changes

Script review

Delineating Differences with Previous Results

Conclusion

Angular Forms Validation: Part III - Async Validators gotchas

I. Absence of Error Message in UI after Async Validation Completion

II. Async Validators start simultaneously on parent and child

II.A Status of the parent not updated as expected

II.B A synchronous validator failure does not prevent async validator from triggering

Conclusion

Angular Forms Validation: Part II - FormGroup Validation

Example: Password Confirmation Form

Implementing FormGroup Validator

Implementing a FormGroup Async Validator

Highlighting FormGroup Validation Errors on the Controls

Conclusion

Angular Forms Validation: Part I - Single control validation

Let's start from the simplest possible example

Adding synchronous validation to the FormControl

Implement asynchronous validator.

Validators execution order

Conclusion

1. Full ISO datetime with ending `Z`

2. Full ISO datetime without `Z`